org.apache.ldap.server
Interface BackingStore

All Known Subinterfaces:
ContextPartition, PartitionNexus
All Known Implementing Classes:
AbstractContextPartition, RootNexus

public interface BackingStore

An interface to a store for JNDI Attributes within a hierarchical namespace. Currently we only have a BackingStore designed for managing LDAP/X.500 namespaces although foreseeably other hierarchical namespaces (directories) can have BackingStore's implemented for them. A BackingStore contains the set of operations that can be performed on a JNDI Attributes.

Version:
$Rev: 159259 $
Author:
Apache Directory Project

Method Summary
 void add(java.lang.String upName, javax.naming.Name normName, javax.naming.directory.Attributes entry)
          Adds an entry to this BackingStore.
 void close()
          Closes or shuts down this BackingStore.
 void delete(javax.naming.Name name)
          Deletes a leaf entry from this BackingStore: non-leaf entries cannot be deleted until this operation has been applied to their children.
 boolean hasEntry(javax.naming.Name name)
          Fast operation to check and see if a particular entry exists.
 boolean isClosed()
          Checks to see if this BackingStore has been closed or shut down.
 boolean isSuffix(javax.naming.Name name)
          Checks to see if name is a context suffix.
 javax.naming.NamingEnumeration list(javax.naming.Name base)
          A specialized form of one level search used to return a minimal set of information regarding child entries under a base.
 javax.naming.directory.Attributes lookup(javax.naming.Name name)
          Looks up an entry by distinguished/absolute name.
 javax.naming.directory.Attributes lookup(javax.naming.Name dn, java.lang.String[] attrIds)
          Looks up an entry by distinguished name.
 void modify(javax.naming.Name name, int modOp, javax.naming.directory.Attributes mods)
          Modifies an entry by adding, removing or replacing a set of attributes.
 void modify(javax.naming.Name name, javax.naming.directory.ModificationItem[] mods)
          Modifies an entry by using a combination of adds, removes or replace operations using a set of ModificationItems.
 void modifyRn(javax.naming.Name name, java.lang.String newRn, boolean deleteOldRn)
          Modifies an entry by changing its relative name.
 void move(javax.naming.Name oriChildName, javax.naming.Name newParentName)
          Transplants a child entry, to a position in the namespace under a new parent entry.
 void move(javax.naming.Name oriChildName, javax.naming.Name newParentName, java.lang.String newRn, boolean deleteOldRn)
          Transplants a child entry, to a position in the namespace under a new parent entry and changes the RN of the child entry which can optionally have its old RN attributes removed.
 javax.naming.NamingEnumeration search(javax.naming.Name base, java.util.Map env, org.apache.ldap.common.filter.ExprNode filter, javax.naming.directory.SearchControls searchCtls)
          Conducts a search against this BackingStore.
 void sync()
          Cue to BackingStores with caches to flush entry and index changes to disk.
 

Method Detail

delete

public void delete(javax.naming.Name name)
            throws javax.naming.NamingException
Deletes a leaf entry from this BackingStore: non-leaf entries cannot be deleted until this operation has been applied to their children.

Parameters:
name - the normalized distinguished/absolute name of the entry to delete from this BackingStore.
Throws:
javax.naming.NamingException - if there are any problems

add

public void add(java.lang.String upName,
                javax.naming.Name normName,
                javax.naming.directory.Attributes entry)
         throws javax.naming.NamingException
Adds an entry to this BackingStore.

Parameters:
upName - the user provided distinguished/absolute name of the entry
normName - the normalized distinguished/absolute name of the entry
entry - the entry to add to this BackingStore
Throws:
javax.naming.NamingException - if there are any problems

modify

public void modify(javax.naming.Name name,
                   int modOp,
                   javax.naming.directory.Attributes mods)
            throws javax.naming.NamingException
Modifies an entry by adding, removing or replacing a set of attributes.

Parameters:
name - the normalized distinguished/absolute name of the entry to modify
modOp - the modification operation to perform on the entry which is one of constants specified by the DirContext interface: ADD_ATTRIBUTE, REMOVE_ATTRIBUTE, REPLACE_ATTRIBUTE.
mods - the attributes and their values used to affect the modification with.
Throws:
javax.naming.NamingException - if there are any problems
See Also:
DirContext, DirContext.ADD_ATTRIBUTE, DirContext.REMOVE_ATTRIBUTE, DirContext.REPLACE_ATTRIBUTE

modify

public void modify(javax.naming.Name name,
                   javax.naming.directory.ModificationItem[] mods)
            throws javax.naming.NamingException
Modifies an entry by using a combination of adds, removes or replace operations using a set of ModificationItems.

Parameters:
name - the normalized distinguished/absolute name of the entry to modify
mods - the ModificationItems used to affect the modification with
Throws:
javax.naming.NamingException - if there are any problems
See Also:
ModificationItem

list

public javax.naming.NamingEnumeration list(javax.naming.Name base)
                                    throws javax.naming.NamingException
A specialized form of one level search used to return a minimal set of information regarding child entries under a base. Convenience method used to optimize operations rather than conducting a full search with retrieval.

Parameters:
base - the base distinguished/absolute name for the search/listing
Returns:
a NamingEnumeration containing objects of type DbSearchResult
Throws:
javax.naming.NamingException - if there are any problems

search

public javax.naming.NamingEnumeration search(javax.naming.Name base,
                                             java.util.Map env,
                                             org.apache.ldap.common.filter.ExprNode filter,
                                             javax.naming.directory.SearchControls searchCtls)
                                      throws javax.naming.NamingException
Conducts a search against this BackingStore. Namespace specific parameters for search are contained within the environment using namespace specific keys into the hash. For example in the LDAP namespace a BackingStore implementation may look for search Controls using a namespace specific or implementation specific key for the set of LDAP Controls.

Parameters:
base - the normalized distinguished/absolute name of the search base
env - the environment under which operation occurs
filter - the root node of the filter expression tree
searchCtls - the search controls
Returns:
a NamingEnumeration containing objects of type SearchResult.
Throws:
javax.naming.NamingException - if there are any problems

lookup

public javax.naming.directory.Attributes lookup(javax.naming.Name name)
                                         throws javax.naming.NamingException
Looks up an entry by distinguished/absolute name. This is a simplified version of the search operation used to point read an entry used for convenience.

Parameters:
name - the normalized distinguished name of the object to lookup
Returns:
an Attributes object representing the entry
Throws:
javax.naming.NamingException - if there are any problems

lookup

public javax.naming.directory.Attributes lookup(javax.naming.Name dn,
                                                java.lang.String[] attrIds)
                                         throws javax.naming.NamingException
Looks up an entry by distinguished name. This is a simplified version of the search operation used to point read an entry used for convenience with a set of attributes to return. If the attributes are null or emty this defaults to the lookup opertion without the attributes.

Parameters:
dn - the normalized distinguished name of the object to lookup
attrIds - the set of attributes to return
Returns:
an Attributes object representing the entry
Throws:
javax.naming.NamingException - if there are any problems

hasEntry

public boolean hasEntry(javax.naming.Name name)
                 throws javax.naming.NamingException
Fast operation to check and see if a particular entry exists.

Parameters:
name - the normalized distinguished/absolute name of the object to check for existance
Returns:
true if the entry exists, false if it does not
Throws:
javax.naming.NamingException - if there are any problems

isSuffix

public boolean isSuffix(javax.naming.Name name)
                 throws javax.naming.NamingException
Checks to see if name is a context suffix.

Parameters:
name - the normalized distinguished/absolute name of the context
Returns:
true if the name is a context suffix, false if it is not.
Throws:
javax.naming.NamingException - if there are any problems

modifyRn

public void modifyRn(javax.naming.Name name,
                     java.lang.String newRn,
                     boolean deleteOldRn)
              throws javax.naming.NamingException
Modifies an entry by changing its relative name. Optionally attributes associated with the old relative name can be removed from the entry. This makes sense only in certain namespaces like LDAP and will be ignored if it is irrelavent.

Parameters:
name - the normalized distinguished/absolute name of the entry to modify the RN of.
newRn - the new RN of the entry specified by name
deleteOldRn - boolean flag which removes the old RN attribute from the entry if set to true, and has no affect if set to false
Throws:
javax.naming.NamingException - if there are any problems

move

public void move(javax.naming.Name oriChildName,
                 javax.naming.Name newParentName)
          throws javax.naming.NamingException
Transplants a child entry, to a position in the namespace under a new parent entry.

Parameters:
newParentName - the normalized distinguished/absolute name of the new parent to move the target entry to
oriChildName - the normalized distinguished/absolute name of the original child name representing the child entry to move
Throws:
javax.naming.NamingException - if there are any problems

move

public void move(javax.naming.Name oriChildName,
                 javax.naming.Name newParentName,
                 java.lang.String newRn,
                 boolean deleteOldRn)
          throws javax.naming.NamingException
Transplants a child entry, to a position in the namespace under a new parent entry and changes the RN of the child entry which can optionally have its old RN attributes removed. The removal of old RN attributes may not make sense in all namespaces. If the concept is undefined in a namespace this parameters is ignored. An example of a namespace where this parameter is significant is the LDAP namespace.

Parameters:
oriChildName - the normalized distinguished/absolute name of the original child name representing the child entry to move
newParentName - the normalized distinguished/absolute name of the new parent to move the targeted entry to
newRn - the new RN of the entry
deleteOldRn - boolean flag which removes the old RN attribute from the entry if set to true, and has no affect if set to false
Throws:
javax.naming.NamingException - if there are any problems

sync

public void sync()
          throws javax.naming.NamingException
Cue to BackingStores with caches to flush entry and index changes to disk.

Throws:
javax.naming.NamingException - if there are problems flushing caches

close

public void close()
           throws javax.naming.NamingException
Closes or shuts down this BackingStore. Operations against closed BackingStores will fail.

Throws:
javax.naming.NamingException - if there are problems shutting down

isClosed

public boolean isClosed()
Checks to see if this BackingStore has been closed or shut down. Operations against closed BackingStores will fail.

Returns:
true if shut down, false otherwise