Backend.java revision c0a5d19fa897c532ced3e13e01f18f869270e9a0
/*
* CDDL HEADER START
*
* The contents of this file are subject to the terms of the
* Common Development and Distribution License, Version 1.0 only
* (the "License"). You may not use this file except in compliance
* with the License.
*
* You can obtain a copy of the license at legal-notices/CDDLv1_0.txt
* See the License for the specific language governing permissions
* and limitations under the License.
*
* When distributing Covered Code, include this CDDL HEADER in each
* file and include the License file at legal-notices/CDDLv1_0.txt.
* If applicable, add the following below this CDDL HEADER, with the
* fields enclosed by brackets "[]" replaced with your own identifying
* information:
* Portions Copyright [yyyy] [name of copyright owner]
*
* CDDL HEADER END
*
*
* Copyright 2006-2008 Sun Microsystems, Inc.
* Portions Copyright 2014-2015 ForgeRock AS
*/
/**
* This class defines the set of methods and structures that must be
* implemented for a Directory Server backend.
*
* @param <C>
* the type of the BackendCfg for the current backend
*/
mayInstantiate=false,
mayExtend=true,
mayInvoke=false)
public abstract class Backend<C extends Configuration>
// should have been BackendCfg instead of Configuration
{
/**
* The backend that holds a portion of the DIT that is hierarchically above
* the information in this backend.
*/
private Backend<?> parentBackend;
/**
* The set of backends that hold portions of the DIT that are hierarchically
* below the information in this backend.
*/
/** The backend monitor associated with this backend. */
private BackendMonitor backendMonitor;
/** Indicates whether this is a private backend or one that holds user data. */
private boolean isPrivateBackend;
/** The unique identifier for this backend. */
/** The writability mode for this backend. */
/** The set of persistent searches registered with this backend. */
/**
* Configure this backend based on the information in the provided configuration.
* When the method returns, the backend will have been configured (ready to be opened) but still unable
* to process operations.
*
* @param cfg The configuration of this backend.
* @param serverContext The server context for this instance
*
* @throws ConfigException
* If there is an error in the configuration.
*/
/**
* Indicates whether the provided configuration is acceptable for
* this backend. It should be possible to call this method on an
* uninitialized backend instance in order to determine whether the
* backend would be able to use the provided configuration.
* <BR><BR>
* Note that implementations which use a subclass of the provided
* configuration class will likely need to cast the configuration
* to the appropriate subclass type.
*
* @param configuration The backend configuration for which
* to make the determination.
* @param unacceptableReasons A list that may be used to hold the
* reasons that the provided
* configuration is not acceptable.
* @param serverContext this Directory Server instance's server context
*
* @return {@code true} if the provided configuration is acceptable
* for this backend, or {@code false} if not.
*/
public boolean isConfigurationAcceptable(
{
// This default implementation does not perform any special
// validation. It should be overridden by backend implementations
// that wish to perform more detailed validation.
return true;
}
/**
* Opens this backend based on the information provided when the backend was configured.
* It also should open any underlying storage and register all suffixes with the server.
*
* @see #configureBackend
*
* @throws ConfigException If an unrecoverable problem arises while opening the backend.
*
* @throws InitializationException If a problem occurs during opening that is not
* related to the server configuration.
*/
/**
* Performs any necessary work to finalize this backend. The backend must be an opened backend,
* so do not use this method on backends where only <code>configureBackend()</code> has been called.
* This may be called during the Directory Server shutdown process or if a backend is disabled
* with the server online.
* It must not return until the backend is closed.
* <p>
* This method may not throw any exceptions. If any problems are encountered,
* then they may be logged but the closure should progress as completely as
* possible.
* <p>
*/
public final void finalizeBackend()
{
{
}
closeBackend();
}
/**
* Performs any necessary work to finally close this backend, particularly
* closing any underlying databases or connections and deregistering
* any suffixes that it manages with the Directory Server.
* <p>
* It will be called as final step of <code>finalizeBackend()</code>,
* so subclasses might override it.
* </p>
*/
public void closeBackend()
{
}
/**
* Retrieves the set of base-level DNs that may be used within this
* backend.
*
* @return The set of base-level DNs that may be used within this
* backend.
*/
public abstract DN[] getBaseDNs();
/**
* Attempts to pre-load all the entries stored within this backend
* into the entry cache. Note that the caller must ensure that the
* backend stays in read-only state until this method returns as
* no entry locking is performed during this operation. Also note
* that any backend implementing this method should implement pre-
* load progress reporting and error handling specific to its own
* implementation.
*
* @throws UnsupportedOperationException if backend does not
* support this operation.
*/
public abstract void preloadEntryCache() throws UnsupportedOperationException;
/**
* Indicates whether search operations which target the specified
* attribute in the indicated manner would be considered indexed
* in this backend. The operation should be considered indexed only
* if the specified operation can be completed efficiently within
* the backend.
* <BR><BR>
* Note that this method should return a general result that covers
* all values of the specified attribute. If a the specified
* attribute is indexed in the indicated manner but some particular
* values may still be treated as unindexed (e.g., if the number of
* entries with that attribute value exceeds some threshold), then
* this method should still return {@code true} for the specified
* attribute and index type.
*
* @param attributeType The attribute type for which to make the
* determination.
* @param indexType The index type for which to make the
* determination.
*
* @return {@code true} if search operations targeting the
* specified attribute in the indicated manner should be
* considered indexed, or {@code false} if not.
*/
/**
* Indicates whether extensible match search operations that target
* the specified attribute with the given matching rule should be
* considered indexed in this backend.
*
* @param attributeType The attribute type for which to make the
* determination.
* @param matchingRule The matching rule for which to make the
* determination.
*
* @return {@code true} if extensible match search operations
* targeting the specified attribute with the given
* matching rule should be considered indexed, or
* {@code false} if not.
*/
{
return false; // FIXME This should be overridden by the JE Backend at least!
}
/**
* Indicates whether a subtree search using the provided filter
* would be indexed in this backend. This default implementation
* uses a rough set of logic that makes a best-effort determination.
* Subclasses that provide a more complete indexing mechanism may
* wish to override this method and provide a more accurate result.
*
* @param filter The search filter for which to make the
* determination.
*
* @return {@code true} if it is believed that the provided filter
* would be indexed in this backend, or {@code false} if
* not.
*/
{
switch (filter.getFilterType())
{
case AND:
// At least one of the subordinate filter components must be
// indexed.
{
if (isIndexed(f))
{
return true;
}
}
return false;
case OR:
{
if (! isIndexed(f))
{
return false;
}
}
case NOT:
// NOT filters are not considered indexed by default.
return false;
case EQUALITY:
case SUBSTRING:
case GREATER_OR_EQUAL:
case LESS_OR_EQUAL:
case PRESENT:
case APPROXIMATE_MATCH:
case EXTENSIBLE_MATCH:
// The attribute type must be provided for us to make the
// determination. If a matching rule ID is provided, then
// we'll use it as well, but if not then we'll use the
// default equality matching rule for the attribute type.
{
return false;
}
if (matchingRuleID != null)
{
}
else
{
}
// FIXME isIndexed() always return false down below
default:
return false;
}
}
/**
* Retrieves the requested entry from this backend. Note that the
* caller must hold a read or write lock on the specified DN.
*
* @param entryDN The distinguished name of the entry to retrieve.
*
* @return The requested entry, or {@code null} if the entry does
* not exist.
*
* @throws DirectoryException If a problem occurs while trying to
* retrieve the entry.
*/
/**
* Indicates whether the requested entry has any subordinates.
*
* @param entryDN The distinguished name of the entry.
*
* @return {@code ConditionResult.TRUE} if the entry has one or more
* subordinates or {@code ConditionResult.FALSE} otherwise
* or {@code ConditionResult.UNDEFINED} if it can not be
* determined.
*
* @throws DirectoryException If a problem occurs while trying to
* retrieve the entry.
*/
/**
* Retrieves the number of subordinates for the requested entry.
*
* @param entryDN The distinguished name of the entry.
*
* @param subtree <code>true</code> to include all entries from the
* requested entry to the lowest level in the
* tree or <code>false</code> to only include
* the entries immediately below the requested
* entry.
*
* @return The number of subordinate entries for the requested entry
* or -1 if it can not be determined.
*
* @throws DirectoryException If a problem occurs while trying to
* retrieve the entry.
*/
/**
* Indicates whether an entry with the specified DN exists in the
* backend. The default implementation obtains a read lock and calls
* {@code getEntry}, but backend implementations may override this
* with a more efficient version that does not require a lock. The
* caller is not required to hold any locks on the specified DN.
*
* @param entryDN The DN of the entry for which to determine
* existence.
*
* @return {@code true} if the specified entry exists in this
* backend, or {@code false} if it does not.
*
* @throws DirectoryException If a problem occurs while trying to
* make the determination.
*/
{
}
/**
* Adds the provided entry to this backend. This method must ensure
* that the entry is appropriate for the backend and that no entry
* already exists with the same DN. The caller must hold a write
* lock on the DN of the provided entry.
*
* @param entry The entry to add to this backend.
* @param addOperation The add operation with which the new entry
* is associated. This may be {@code null}
* for adds performed internally.
*
* @throws DirectoryException If a problem occurs while trying to
* add the entry.
*
* @throws CanceledOperationException If this backend noticed and
* reacted to a request to
* cancel or abandon the add
* operation.
*/
/**
* Removes the specified entry from this backend. This method must
* ensure that the entry exists and that it does not have any
* subordinate entries (unless the backend supports a subtree delete
* operation and the client included the appropriate information in
* the request). The caller must hold a write lock on the provided
* entry DN.
*
* @param entryDN The DN of the entry to remove from this
* backend.
* @param deleteOperation The delete operation with which this
* action is associated. This may be
* {@code null} for deletes performed
* internally.
*
* @throws DirectoryException If a problem occurs while trying to
* remove the entry.
*
* @throws CanceledOperationException If this backend noticed and
* reacted to a request to
* cancel or abandon the
* delete operation.
*/
/**
* Replaces the specified entry with the provided entry in this
* backend. The backend must ensure that an entry already exists
* with the same DN as the provided entry. The caller must hold a
* write lock on the DN of the provided entry.
*
* @param oldEntry
* The original entry that is being replaced.
* @param newEntry
* The new entry to use in place of the existing entry with
* the same DN.
* @param modifyOperation
* The modify operation with which this action is
* associated. This may be {@code null} for modifications
* performed internally.
* @throws DirectoryException
* If a problem occurs while trying to replace the entry.
* @throws CanceledOperationException
* If this backend noticed and reacted to a request to
* cancel or abandon the modify operation.
*/
/**
* any subordinate entries as necessary. This must ensure that an
* entry already exists with the provided current DN, and that no
* entry exists with the target DN of the provided entry. The caller
* must hold write locks on both the current DN and the new DN for
* the entry.
*
* @param currentDN
* @param entry
* The new content to use for the entry.
* @param modifyDNOperation
* The modify DN operation with which this action is
* associated. This may be {@code null} for modify DN
* operations performed internally.
* @throws DirectoryException
* If a problem occurs while trying to perform the rename.
* @throws CanceledOperationException
* If this backend noticed and reacted to a request to
* cancel or abandon the modify DN operation.
*/
/**
* Processes the specified search in this backend. Matching entries
* should be provided back to the core server using the
* {@code SearchOperation.returnEntry} method. The caller is not
* required to have any locks when calling this operation.
*
* @param searchOperation The search operation to be processed.
*
* @throws DirectoryException If a problem occurs while processing
* the search.
*
* @throws CanceledOperationException If this backend noticed and
* reacted to a request to
* cancel or abandon the
* search operation.
*/
/**
* Retrieves the OIDs of the controls that may be supported by this
* backend.
*
* @return The OIDs of the controls that may be supported by this
* backend.
*/
/**
* Indicates whether this backend supports the specified control.
*
* @param controlOID The OID of the control for which to make the
* determination.
*
* @return {@code true} if this backends supports the control with
* the specified OID, or {@code false} if it does not.
*/
{
}
/**
* Retrieves the OIDs of the features that may be supported by this
* backend.
*
* @return The OIDs of the features that may be supported by this
* backend.
*/
/** Enumeration of optional backend operations. */
public static enum BackendOperation
{
/** Indicates whether this backend supports indexing attributes to speed up searches. */
/** Indicates whether this backend supports exporting the data it contains to an LDIF file. */
/** Indicates whether this backend supports importing its data from an LDIF file. */
/**
* Indicates whether this backend provides a backup mechanism of any kind. This method is used
* by the backup process when backing up all backends to determine whether this backend is one
* that should be skipped. It should only return {@code true} for backends that it is not
* possible to archive directly (e.g., those that don't store their data locally, but rather
* pass through requests to some other repository).
*/
/** Indicates whether this backend can restore a backup. */
}
/**
* Indicates whether this backend supports the provided backend operation.
*
* @param backendOperation
* the backend operation
* @return {@code true} if this backend supports the provided backend operation, {@code false}
* otherwise.
*/
/**
* Exports the contents of this backend to LDIF. This method should
* only be called if {@code supportsLDIFExport} returns
* {@code true}. Note that the server will not explicitly
* initialize this backend before calling this method.
*
* @param exportConfig The configuration to use when performing
* the export.
*
* @throws DirectoryException If a problem occurs while performing
* the LDIF export.
*/
/**
* Imports information from an LDIF file into this backend. This
* method should only be called if {@code supportsLDIFImport}
* returns {@code true}. Note that the server will not explicitly
* initialize this backend before calling this method.
*
* @param importConfig The configuration to use when performing the import.
* @param serverContext The server context
* @return Information about the result of the import processing.
* @throws DirectoryException If a problem occurs while performing
* the LDIF import.
*/
public abstract LDIFImportResult importLDIF(LDIFImportConfig importConfig, ServerContext serverContext)
throws DirectoryException;
/**
* Verify the integrity of the backend instance.
*
* @param verifyConfig
* The verify configuration.
* @return The results of the operation.
* @throws ConfigException
* If an unrecoverable problem arises during initialization.
* @throws InitializationException
* If a problem occurs during initialization that is not related to the server
* configuration.
* @throws DirectoryException
* If a Directory Server error occurs.
*/
{
}
/**
* Rebuild indexes in the backend instance. Note that the server will not explicitly initialize
* this backend before calling this method.
*
* @param rebuildConfig
* The rebuild configuration.
* @throws ConfigException
* If an unrecoverable problem arises during initialization.
* @throws InitializationException
* If a problem occurs during initialization that is not related to the server
* configuration.
* @throws DirectoryException
* If a Directory Server error occurs.
*/
{
}
/**
* Creates a backup of the contents of this backend in a form that
* may be restored at a later date if necessary. This method should
* only be called if {@code supportsBackup} returns {@code true}.
* Note that the server will not explicitly initialize this backend
* before calling this method.
*
* @param backupConfig The configuration to use when performing
* the backup.
*
* @throws DirectoryException If a problem occurs while performing
* the backup.
*/
throws DirectoryException;
/**
* Removes the specified backup if it is possible to do so.
*
* @param backupDirectory The backup directory structure with
* which the specified backup is
* associated.
* @param backupID The backup ID for the backup to be
* removed.
*
* @throws DirectoryException If it is not possible to remove the
* specified backup for some reason
* (e.g., no such backup exists or
* there are other backups that are
* dependent upon it).
*/
throws DirectoryException;
/**
* Restores a backup of the contents of this backend. This method
* should only be called if {@code supportsRestore} returns
* {@code true}. Note that the server will not explicitly
* initialize this backend before calling this method.
*
* @param restoreConfig The configuration to use when performing
* the restore.
*
* @throws DirectoryException If a problem occurs while performing
* the restore.
*/
throws DirectoryException;
/**
* Retrieves the unique identifier for this backend.
*
* @return The unique identifier for this backend.
*/
public final String getBackendID()
{
return backendID;
}
/**
* Specifies the unique identifier for this backend.
*
* @param backendID The unique identifier for this backend.
*/
{
}
/**
* Indicates whether this backend holds private data or user data.
*
* @return {@code true} if this backend holds private data, or
* {@code false} if it holds user data.
*/
public final boolean isPrivateBackend()
{
return isPrivateBackend;
}
/**
* Specifies whether this backend holds private data or user data.
*
* @param isPrivateBackend Specifies whether this backend holds
* private data or user data.
*/
public final void setPrivateBackend(boolean isPrivateBackend)
{
this.isPrivateBackend = isPrivateBackend;
}
/**
* Retrieves the writability mode for this backend.
*
* @return The writability mode for this backend.
*/
public final WritabilityMode getWritabilityMode()
{
return writabilityMode;
}
/**
* Specifies the writability mode for this backend.
*
* @param writabilityMode The writability mode for this backend.
*/
{
}
/**
* Retrieves the backend monitor that is associated with this
* backend.
*
* @return The backend monitor that is associated with this
* backend, or {@code null} if none has been assigned.
*/
public final BackendMonitor getBackendMonitor()
{
return backendMonitor;
}
/**
* Registers the provided persistent search operation with this backend so
* that it will be notified of any add, delete, modify, or modify DN
* operations that are performed.
*
* @param persistentSearch
* The persistent search operation to register with this backend
* @throws DirectoryException
* If a problem occurs while registering the persistent search
*/
{
{
{
}
});
}
/**
* Returns the persistent searches currently active against this local
* backend.
*
* @return the list of persistent searches currently active against this local
* backend
*/
{
return persistentSearches;
}
/**
* Sets the backend monitor for this backend.
*
* @param backendMonitor The backend monitor for this backend.
*/
{
this.backendMonitor = backendMonitor;
}
/**
* Retrieves the total number of entries contained in this backend,
* if that information is available.
*
* @return The total number of entries contained in this backend,
* or -1 if that information is not available.
*/
public abstract long getEntryCount();
/**
* Retrieves the parent backend for this backend.
*
* @return The parent backend for this backend, or {@code null} if
* there is none.
*/
public final Backend<?> getParentBackend()
{
return parentBackend;
}
/**
* Specifies the parent backend for this backend.
*
* @param parentBackend The parent backend for this backend.
*/
{
this.parentBackend = parentBackend;
}
/**
* Retrieves the set of subordinate backends for this backend.
*
* @return The set of subordinate backends for this backend, or an
* empty array if none exist.
*/
public final Backend<?>[] getSubordinateBackends()
{
return subordinateBackends;
}
/**
* Adds the provided backend to the set of subordinate backends for
* this backend.
*
* @param subordinateBackend The backend to add to the set of
* subordinate backends for this
* backend.
*/
{
for (Backend<?> b : subordinateBackends)
{
backendSet.add(b);
}
{
}
}
/**
* Removes the provided backend from the set of subordinate backends
* for this backend.
*
* @param subordinateBackend The backend to remove from the set of
* subordinate backends for this
* backend.
*/
{
boolean found = false;
for (Backend<?> b : subordinateBackends)
{
if (b.equals(subordinateBackend))
{
found = true;
}
else
{
backendList.add(b);
}
}
if (found)
{
}
}
/**
* Indicates whether this backend should be used to handle
* operations for the provided entry.
*
* @param entryDN The DN of the entry for which to make the
* determination.
*
* @return {@code true} if this backend handles operations for the
* provided entry, or {@code false} if it does not.
*/
{
{
{
for (Backend<?> b : subordinateBackends)
{
if (b.handlesEntry(entryDN))
{
return false;
}
}
return true;
}
}
return false;
}
/**
* Indicates whether a backend should be used to handle operations
* for the provided entry given the set of base DNs and exclude DNs.
*
* @param entryDN The DN of the entry for which to make the
* determination.
* @param baseDNs The set of base DNs for the backend.
* @param excludeDNs The set of DNs that should be excluded from
* the backend.
*
* @return {@code true} if the backend should handle operations for
* the provided entry, or {@code false} if it does not.
*/
{
{
{
return true;
}
}
return false;
}
{
{
return false;
}
{
{
return true;
}
}
return false;
}
}