/*
 *  Licensed to the Apache Software Foundation (ASF) under one
 *  or more contributor license agreements.  See the NOTICE file
 *  distributed with this work for additional information
 *  regarding copyright ownership.  The ASF licenses this file
 *  to you under the Apache License, Version 2.0 (the
 *  "License"); you may not use this file except in compliance
 *  with the License.  You may obtain a copy of the License at
 * 
 *    http://www.apache.org/licenses/LICENSE-2.0
 * 
 *  Unless required by applicable law or agreed to in writing,
 *  software distributed under the License is distributed on an
 *  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
 *  KIND, either express or implied.  See the License for the
 *  specific language governing permissions and limitations
 *  under the License.
 * 
 */
package org.apache.directory.server.core.api;


import java.io.IOException;
import java.util.List;
import java.util.Set;

import org.apache.directory.api.ldap.codec.api.LdapApiService;
import org.apache.directory.api.ldap.model.csn.Csn;
import org.apache.directory.api.ldap.model.entry.Entry;
import org.apache.directory.api.ldap.model.exception.LdapException;
import org.apache.directory.api.ldap.model.ldif.LdifEntry;
import org.apache.directory.api.ldap.model.name.Dn;
import org.apache.directory.api.ldap.model.schema.SchemaManager;
import org.apache.directory.api.ldap.util.tree.DnNode;
import org.apache.directory.api.util.TimeProvider;
import org.apache.directory.server.core.api.administrative.AccessControlAdministrativePoint;
import org.apache.directory.server.core.api.administrative.CollectiveAttributeAdministrativePoint;
import org.apache.directory.server.core.api.administrative.SubschemaAdministrativePoint;
import org.apache.directory.server.core.api.administrative.TriggerExecutionAdministrativePoint;
import org.apache.directory.server.core.api.changelog.ChangeLog;
import org.apache.directory.server.core.api.entry.ServerEntryFactory;
import org.apache.directory.server.core.api.event.EventService;
import org.apache.directory.server.core.api.interceptor.Interceptor;
import org.apache.directory.server.core.api.journal.Journal;
import org.apache.directory.server.core.api.partition.Partition;
import org.apache.directory.server.core.api.partition.PartitionNexus;
import org.apache.directory.server.core.api.schema.SchemaPartition;
import org.apache.directory.server.core.api.subtree.SubentryCache;
import org.apache.directory.server.core.api.subtree.SubtreeEvaluator;


/**
 * All the features a DirectroyService instance must implement. This gives a control
 * of the Directory based server. 
 *
 * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
 */
public interface DirectoryService extends ServerEntryFactory
{
    String JNDI_KEY = DirectoryService.class.getName();


    /**
     * Reverts the server's state to an earlier revision.  Note that the revsion number
     * still increases to revert back even though the state reverted to is the same.
     * Note that implementations may lock the server from making changes or searching
     * the directory until this operation has completed.
     *
     * @param revision the revision number to revert to
     * @return the new revision reached by applying all changes needed to revert to the
     * original state
     * @throws LdapException if there are problems reverting back to the earlier state
     */
    long revert( long revision ) throws LdapException;


    /**
     * Reverts the server's state to the latest tagged snapshot if one was taken.  If
     * there is no tag a illegal state exception will result.  If the latest revision
     * is not earlier than the current revision (both are same), then no changes were
     * made to the directory to be reverted.  In this case we return the current
     * revision and do nothing logging the fact that we ignored the request to revert.
     *
     * @return the new revision reached by applying all changes needed to revert
     * to the new state or the same version before this call if no revert actually
     * took place
     * @throws LdapException if there are problems reverting back to the earlier state
     */
    long revert() throws LdapException;


    PartitionNexus getPartitionNexus();


    void addPartition( Partition partition ) throws LdapException;


    void removePartition( Partition partition ) throws LdapException;


    /**
     * @return The Directory Service SchemaManager
     */
    SchemaManager getSchemaManager();


    /**
     * @return The LDAP codec service.
     */
    LdapApiService getLdapCodecService();


    /**
     * @return The referral manager
     */
    ReferralManager getReferralManager();


    /**
     * Set the referralManager
     * 
     * @param referralManager The initialized referralManager
     */
    void setReferralManager( ReferralManager referralManager );


    /**
     * @return The schema partition
     */
    SchemaPartition getSchemaPartition();


    /**
     * Set the SchemaPartition
     * @param schemaPartition the SchemaPartition instance
     */
    void setSchemaPartition( SchemaPartition schemaPartition );


    EventService getEventService();


    /**
     * @param eventService The {@link EventService} instance
     */
    void setEventService( EventService eventService );


    /**
     * Starts up this service.
     * 
     * @throws LdapException if failed to start up
     */
    void startup() throws LdapException;


    /**
     * Shuts down this service.
     * 
     * @throws LdapException if failed to shut down
     */
    void shutdown() throws LdapException;


    /**
     * Calls {@link Partition#sync()} for all registered {@link Partition}s.
     * @throws LdapException if synchronization failed
     */
    void sync() throws LdapException;


    /**
     * Returns <tt>true</tt> if this service is started.
     * @return true if the service has started, false otherwise
     */
    boolean isStarted();


    /**
     * @return The Admin session
     */
    CoreSession getAdminSession();


    /**
     * @return Returns the hash mapping the Dn of a subentry to its SubtreeSpecification/types
     **/
    SubentryCache getSubentryCache();


    /**
     * @return Returns the subentry evaluator
     */
    SubtreeEvaluator getEvaluator();


    /**
     * Gets a logical session to perform operations on this DirectoryService
     * as the anonymous user.  This bypasses authentication without
     * propagating a bind operation into the core.
     *
     * @return a logical session as the anonymous user
     * @throws LdapException If we weren't able to get the session
     */
    CoreSession getSession() throws LdapException;


    /**
     * Gets a logical session to perform operations on this DirectoryService
     * as a specific user.  This bypasses authentication without propagating
     * a bind operation into the core.
     *
     * @param principal The Principal
     * @return a logical session as a specific user
     * @throws LdapException If we weren't able to get the session
     */
    CoreSession getSession( LdapPrincipal principal ) throws LdapException;


    /**
     * Gets a logical session to perform operations on this DirectoryService
     * as a specific user with a separate authorization principal.  This
     * bypasses authentication without propagating a bind operation into the
     * core.
     *
     * @param principalDn The principal Dn
     * @param credentials The principal credentials
     * @return a logical session as a specific user
     * @throws LdapException If we weren't able to get the session
     */
    CoreSession getSession( Dn principalDn, byte[] credentials ) throws LdapException;


    /**
     * Gets a logical session to perform operations on this DirectoryService
     * as a specific user with a separate authorization principal.  This
     * bypasses authentication without propagating a bind operation into the
     * core.
     *
     * @param principalDn The principal Dn
     * @param credentials The principal credentials
     * @param saslMechanism The SASL mechanisms
     * @param saslAuthId The SASL authorization ID
     * @return a logical session as a specific user
     * @throws LdapException If we weren't able to get the session
     */
    CoreSession getSession( Dn principalDn, byte[] credentials, String saslMechanism, String saslAuthId )
        throws LdapException;


    /**
     * Set the instance Identifier
     * 
     * @param instanceId The instance identifier
     */
    void setInstanceId( String instanceId );


    /**
     * @return The instance identifier
     */
    String getInstanceId();


    /**
     * Gets the {@link Partition}s used by this DirectoryService.
     *
     * @return the set of partitions used
     */
    Set<? extends Partition> getPartitions();


    /**
     * Sets {@link Partition}s used by this DirectoryService.
     *
     * @param partitions the partitions to used
     */
    void setPartitions( Set<? extends Partition> partitions );


    /**
     * Returns <tt>true</tt> if access control checks are enabled.
     *
     * @return true if access control checks are enabled, false otherwise
     */
    boolean isAccessControlEnabled();


    /**
     * Sets whether to enable basic access control checks or not.
     *
     * @param accessControlEnabled true to enable access control checks, false otherwise
     */
    void setAccessControlEnabled( boolean accessControlEnabled );


    /**
     * Returns <tt>true</tt> if anonymous access is allowed on entries besides the RootDSE.
     * If the access control subsystem is enabled then access to some entries may not be
     * allowed even when full anonymous access is enabled.
     *
     * @return true if anonymous access is allowed on entries besides the RootDSE, false
     * if anonymous access is allowed to all entries.
     */
    boolean isAllowAnonymousAccess();


    /**
     * Returns <tt>true</tt> if the service requires the userPassword attribute
     * to be masked. It's an option in the server.xml file.
     *
     * @return true if the service requires that the userPassword is to be hidden
     */
    boolean isPasswordHidden();


    /**
     * Sets whether the userPassword attribute is readable, or hidden.
     *
     * @param passwordHidden true to enable hide the userPassword attribute, false otherwise
     */
    void setPasswordHidden( boolean passwordHidden );


    /**
     * Sets whether to allow anonymous access to entries other than the RootDSE.  If the
     * access control subsystem is enabled then access to some entries may not be allowed
     * even when full anonymous access is enabled.
     *
     * @param enableAnonymousAccess true to enable anonymous access, false to disable it
     */
    void setAllowAnonymousAccess( boolean enableAnonymousAccess );


    /**
     * Returns interceptors in the server.
     *
     * @return the interceptors in the server.
     */
    List<Interceptor> getInterceptors();


    /**
     * Returns interceptors in the server.
     *
     * @param operation The operation that the interceptors must implement
     * @return the interceptors in the server.
     */
    List<String> getInterceptors( OperationEnum operation );


    /**
     * Sets the interceptors in the server.
     *
     * @param interceptors the interceptors to be used in the server.
     */
    void setInterceptors( List<Interceptor> interceptors );


    /**
     * Add an interceptor in the first position in the interceptor list.
     * 
     * @param interceptor The added interceptor
     * @throws LdapException If the interceptor can't be added
     */
    void addFirst( Interceptor interceptor ) throws LdapException;


    /**
     * Add an interceptor in the last position in the interceptor list.
     * 
     * @param interceptor The added interceptor
     * @throws LdapException If the interceptor can't be added
     */
    void addLast( Interceptor interceptor ) throws LdapException;


    /**
     * Add an interceptor after a given interceptor in the interceptor list.
     * 
     * @param interceptorName The interceptor name to find
     * @param interceptor The added interceptor
     */
    void addAfter( String interceptorName, Interceptor interceptor );


    /**
     * Remove an interceptor from the list of interceptors
     * @param interceptorName The interceptor to remove
     */
    void remove( String interceptorName );


    /**
     * Sets the journal in the server.
     *
     * @param journal the journal to be used in the server.
     */
    void setJournal( Journal journal );


    /**
     * Returns test directory entries({@link org.apache.directory.api.ldap.model.ldif.LdifEntry}) to be loaded while
     * bootstrapping.
     *
     * @return test entries to load during bootstrapping
     */
    List<LdifEntry> getTestEntries();


    /**
     * Sets test directory entries to be loaded while bootstrapping.
     *
     * @param testEntries the test entries to load while bootstrapping
     */
    void setTestEntries( List<? extends LdifEntry> testEntries );


    /**
     * Returns the instance layout which contains the path for various directories
     *
     * @return the InstanceLayout for this directory service.
     */
    InstanceLayout getInstanceLayout();


    /**
     * Sets the InstanceLayout used by the DirectoryService to store the files
     * @param instanceLayout The InstanceLayout to set
     * @throws IOException If the layout could not be created
     */
    void setInstanceLayout( InstanceLayout instanceLayout ) throws IOException;


    /**
     * Sets the shutdown hook flag which controls whether or not this DirectoryService
     * registers a JVM shutdown hook to flush caches and synchronize to disk safely.  This is
     * enabled by default.
     *
     * @param shutdownHookEnabled true to enable the shutdown hook, false to disable
     */
    void setShutdownHookEnabled( boolean shutdownHookEnabled );


    /**
     * Checks to see if this DirectoryService has registered a JVM shutdown hook
     * to flush caches and synchronize to disk safely.  This is enabled by default.
     *
     * @return true if a shutdown hook is registered, false if it is not
     */
    boolean isShutdownHookEnabled();


    void setExitVmOnShutdown( boolean exitVmOnShutdown );


    boolean isExitVmOnShutdown();


    void setSystemPartition( Partition systemPartition );


    Partition getSystemPartition();


    boolean isDenormalizeOpAttrsEnabled();


    void setDenormalizeOpAttrsEnabled( boolean denormalizeOpAttrsEnabled );


    /**
     * Gets the ChangeLog service for this DirectoryService used for tracking
     * changes (revisions) to the server and using them to revert the server
     * to earlier revisions.
     *
     * @return the change log service
     */
    ChangeLog getChangeLog();


    /**
     * Gets the Journal service for this DirectoryService used for tracking
     * changes to the server.
     *
     * @return the journal service
     */
    Journal getJournal();


    /**
     * Sets the ChangeLog service for this DirectoryService used for tracking
     * changes (revisions) to the server and using them to revert the server
     * to earlier revisions.
     *
     * @param changeLog the change log service to set
     */
    void setChangeLog( ChangeLog changeLog );


    /**
     * Create a new Entry.
     * 
     * @param ldif the String representing the attributes, in LDIF format
     * @param dn the Dn for this new entry
     * @return The new Entry instance
     */
    Entry newEntry( String ldif, String dn );


    /**
     * Gets the operation manager.
     * 
     * @return the OperationManager instance
     */
    OperationManager getOperationManager();


    /**
     * @return The maximum allowed size for an incoming PDU
     */
    int getMaxPDUSize();


    /**
     * Set the maximum allowed size for an incoming PDU
     * @param maxPDUSize A positive number of bytes for the PDU. A negative or
     * null value will be transformed to {@link Integer#MAX_VALUE}
     */
    void setMaxPDUSize( int maxPDUSize );


    /**
     * Get an Interceptor instance from its name
     * @param interceptorName The interceptor's name for which we want the instance
     * @return the interceptor for the given name
     */
    Interceptor getInterceptor( String interceptorName );


    /**
     * Get a new CSN
     * @return The CSN generated for this directory service
     */
    Csn getCSN();


    /**
     * @return the replicaId
     */
    int getReplicaId();


    /**
     * @param replicaId the replicaId to set
     */
    void setReplicaId( int replicaId );


    /**
     * Associates a SchemaManager to the service
     * 
     * @param schemaManager The SchemaManager to associate
     */
    void setSchemaManager( SchemaManager schemaManager );


    /**
     * the time interval at which the DirectoryService's data is flushed to disk
     * 
     * @param syncPeriodMillis the syncPeriodMillis to set
     */
    void setSyncPeriodMillis( long syncPeriodMillis );


    /**
     * @return the syncPeriodMillis
     */
    long getSyncPeriodMillis();


    /**
     * @return The AccessControl AdministrativePoint cache
     */
    DnNode<AccessControlAdministrativePoint> getAccessControlAPCache();


    /**
     * @return The CollectiveAttribute AdministrativePoint cache
     */
    DnNode<CollectiveAttributeAdministrativePoint> getCollectiveAttributeAPCache();


    /**
     * @return The Subschema AdministrativePoint cache
     */
    DnNode<SubschemaAdministrativePoint> getSubschemaAPCache();


    /**
     * @return The TriggerExecution AdministrativePoint cache
     */
    DnNode<TriggerExecutionAdministrativePoint> getTriggerExecutionAPCache();


    /**
     * @return true if the password policy is enabled, false otherwise
     */
    boolean isPwdPolicyEnabled();


    /**
     * Gets the Dn factory.
     *
     * @return the Dn factory
     */
    DnFactory getDnFactory();


    /**
     * Sets the Dn factory.
     * 
     * @param dnFactory The Dn factory to use
     */
    void setDnFactory( DnFactory dnFactory );


    /**
     * Gets the {@link AttributeTypeProvider}.
     * 
     * @return the {@link AttributeTypeProvider}
     */
    AttributeTypeProvider getAtProvider();


    /**
     * Gets the {@link ObjectClassProvider}.
     * 
     * @return the {@link ObjectClassProvider}
     */
    ObjectClassProvider getOcProvider();


    /**
     * Gets the time provider.
     * 
     * @return the time provider
     */
    TimeProvider getTimeProvider();


    /**
     * Sets the time provider.
     * 
     * @param timeProvider the time provider
     */
    void setTimeProvider( TimeProvider timeProvider );
}