Package com.isode.dsapi.util

Class EntryWriter

java.lang.Object
com.isode.dsapi.util.EntryWriter
public class EntryWriter extends Object
The EntryWriter class provides a simple way to build an Entry object which can then to be written to a directory.

EntryWriter is used in two ways: either to create a new entry in the directory, or to modify an existing entry.

When creating a new entry, EntryWriter can derive values from an existing entry.

Callers may add, modify or delete values from the Entry that they are creating with EntryWriter. When the modifications are complete, then by calling apply(DirectorySession, CommonArgs), EntryWriter will perform the appropriate series of operations on the Directory to write the new Entry. 

 // Given a directory entry "cn=nick,o=isode" with
 // the following attributes:
 //   cn=nick
 //   sn=hudson
 //   objectClass=inetorgperson, person, mboxgroup
 //   description="Old description"
 //   mboxGroupMember="notWantedMember, superMember"
 // then the following set of operations

 DN oldDN = new DN("cn=nick,o=isode");
 Selection sel = new Selection(SelectionType.ALL_USER_AND_OPER_ATTRIBUTES);
 Indication ind = ds.read(oldDN, sel, null);
 Entry oldEntry = ind.getEntry(0);

 DN newDN = new DN("cn=harry,o=isode");
 EntryWriter ew = new EntryWriter(oldEntry, newDN);
 // ensure that objectClass contains mboxGroup
 ew.add(AttributeTypes.objectClass, "mboxGroup");
 // force description to be "New description"
 ew.set(AttributeTypes.description, "New description");
 // ensure that mboxGroupMember maultivalued attribute has "wantedMember" value
 ew.add(AttributeTypes.mboxGroupMember,"wantedMember");
 // ensure that mboxGroupMember maultivalued attribute has no "notWantedMember" value
 ew.delete(AttributeTypes.mboxGroupMember,"notWantedMember");
 ew.apply(ds, null);

 // will result in the "cn=nick,o=isode" entry being renamed/relocated to
 // "cn=harry,o=isode" with the following attributes:
 //   cn=harry
 //   sn=hudson
 //   objectclass=inetorgperson, person, mboxgroup
 //   description="New description"
 //   mboxGroupMember=wantedMember, superMember
Since:
14.5
Author:
mst

  • Constructor Details

    • EntryWriter

      public EntryWriter(Entry oldEntry, DN newDn, boolean relocate)
      Constructs a new EntryWriter.
      • if oldEntry is not null, then all of the attribute values from oldEntry will be set in the EntryWriter object, and the result of calling apply(DirectorySession, CommonArgs) is that oldEntry will be renamed/relocated to newDn and modified to gain specified values
      • if oldEntry has the same DN as newDN, then the result of calling apply(DirectorySession, CommonArgs) is that oldEntry will be modified.
      In normal entry rename directory operation changing both RDN and parent DN (relocation) is not allowed in single operation. EntryWriter supports this by performing it in 2 steps: renaming (changing RDN) and relocation (changing parent DN). In some situations it may be required to forbid relocation and update RDN only so relocation is optional. Both operations are performed only when required and allowed:
      • If oldEntry is null then new Entry at newDN will be created
      • If oldEntry RDN is different from newDn RDN - it will be renamed
      • If oldEntry parent DN is different from newDn parent DN and relocation is allowed then it will be relocated in DIT
      Parameters:
      oldEntry - old entry (may be null if an entry is to be created)
      newDn - new DN; If the parent dn is different from old entry's dn, it will be relocated only if relocate flag is true, else just the RDN will be renamed (null allowed but not when oldEntry is null)
      relocate - allow to relocate entry (for false only RDN will be changed)

    • EntryWriter

      public EntryWriter(Entry oldEntry, DN newDn)
      Constructs a new EntryWriter.
      • if oldEntry is not null, then all of the attribute values from oldEntry will be set in the EntryWriter object, and the result of calling apply(DirectorySession, CommonArgs) is that oldEntry will be renamed/relocated to newDn and modified to gain specified values
      • if oldEntry has the same DN as newDN, then the result of calling apply(DirectorySession, CommonArgs) is that oldEntry will be modified.
      In normal entry rename directory operation changing both RDN and parent DN (relocation) is not allowed in single operation. EntryWriter supports this by performing it in 2 steps: renaming (changing RDN) and relocation (changing parent DN). In some situations it may be required to forbid relocation and update RDN only so relocation is optional. Both operations are performed only when required and allowed:
      • If oldEntry is null then new Entry at newDN will be created
      • If oldEntry RDN is different from newDn RDN - it will be renamed
      • If oldEntry parent DN is different from newDn parent DN and relocation is allowed then it will be relocated in DIT
      In this constructor relocation is allowed!
      Parameters:
      oldEntry - old entry (may be null if an entry is to be created)
      newDn - new DN; If the parent dn is different from old entry's dn, it will be relocated only (null allowed but not when oldEntry is null)

    • EntryWriter

      public EntryWriter(DN newDn)
      Constructs a new EntryWriter supposed to create new Entry
      Parameters:
      newDn - new entry DN (not null)
      Throws:
      NullPointerException - if newDn is null
      Since:
      15.0

    • EntryWriter

      public EntryWriter(Entry entry)
      Constructs a new EntryWriter allowing modify existing entry.
      Parameters:
      entry - existing entry (not null)
      Throws:
      NullPointerException - if entry is null

  • Method Details

    • set

      public void set(AttributeType at, String val) throws BadValueException
      Modify attribute by setting string value to an attribute with string syntax. After the apply operation the attribute type will have the values specified and existing values be removed
      Parameters:
      at - attribute type (not null)
      val - value to set; if null or an empty String (""), the attribute will be deleted
      Throws:
      BadValueException - if value is not a valid LDAP-encoded value for attribute.

    • set

      public void set(AttributeType at, Boolean val) throws BadValueException
      Modify attribute by setting boolean value. After the apply operation the attribute type will have the values specified and existing values be removed
      Parameters:
      at - attribute type (not null)
      val - value to set, if null the attribute would be deleted
      Throws:
      BadValueException - if attribute type is not of type boolean .
      NullPointerException - if attribute type is null

    • setBer

      public void setBer(AttributeType at, byte[] val) throws BadValueException
      Modify attribute by setting BER value. After the apply operation the attribute type will have the values specified and existing values be removed
      Parameters:
      at - attribute type (not null)
      val - value to set , if null or empty the attribute would be deleted
      Throws:
      BadValueException - BadValueException if val is not a valid value for the specified attribute type
      Since:
      14.6
      See Also:

    • setBin

      public void setBin(AttributeType at, byte[] val) throws BadValueException
      Modify attribute by setting binary value. After the apply operation the attribute type will have the values specified and existing values be removed
      Parameters:
      at - attribute type (not null)
      val - value to set,if null or empty the attribute would be deleted
      Throws:
      BadValueException - BadValueException if val is not a valid value for the specified attribute type
      Since:
      14.6
      See Also:

    • add

      public void add(AttributeType at, String val) throws BadValueException
      Modify attribute by adding string value. If the value already exists, it will be ignored.

      For a single valued attribute in the EntryWriter object, this function could be called multiple times. The first time it would add the attribute if it didn't exist in its copy yet; the subsequent times it would update its copy of the attribute value.

      Parameters:
      at - attribute type (not null)
      val - value to set; if null or an empty String (""), no modification will be performed.
      Throws:
      BadValueException - if value is not a valid LDAP-encoded value for attribute.

    • addBin

      public void addBin(AttributeType at, byte[] val) throws BadValueException
      Modify attribute by adding binary value.If the value already exists, it will be ignored.

      For a single valued attribute in the EntryWriter object, this function could be called multiple times. The first time it would add the attribute if it didn't exist in its copy yet; the subsequent times it would update its copy of the attribute value.

      Parameters:
      at - attribute type (not null)
      val - value to set (if null or empty - no modification will be performed)
      Throws:
      BadValueException - BadValueException if val is not a valid value for the specified attribute type
      Since:
      14.6
      See Also:

    • addBer

      public void addBer(AttributeType at, byte[] val) throws BadValueException
      Modify attribute by adding BER value.If the value already exists, it will be ignored.

      For a single valued attribute in the EntryWriter object, this function could be called multiple times. The first time it would add the attribute if it didn't exist in its copy yet; the subsequent times it would update its copy of the attribute value.

      Parameters:
      at - attribute type (not null)
      val - value to set (if null or empty - then no modification will be performed)
      Throws:
      BadValueException - BadValueException if val is not a valid value for the specified attribute type
      Since:
      14.6
      See Also:

    • delete

      public void delete(AttributeType at, String val) throws BadValueException
      Modify attribute by deleting string value. The value will be deleted on apply if it exists in the existing entry else no action would be taken
      Parameters:
      at - attribute type (not null)
      val - value to delete; if null or an empty String (""), then no modification will be performed
      Throws:
      BadValueException - if value is not a valid LDAP-encoded value for attribute.

    • deleteBin

      public void deleteBin(AttributeType at, byte[] val) throws BadValueException
      Modify attribute by deleting binary value. The value will be deleted on apply if it exists in the existing entry else no action would be taken
      Parameters:
      at - attribute type (not null)
      val - value to set (if null or empty - then no modification will be performed)
      Throws:
      BadValueException - BadValueException if val is not a valid value for the specified attribute type
      Since:
      14.6
      See Also:

    • deleteBer

      public void deleteBer(AttributeType at, byte[] val) throws BadValueException
      Modify attribute by deleting BER value.The value will be deleted on apply if it exists in the existing entry else no action would be taken
      Parameters:
      at - attribute type (not null)
      val - value to set (if null or empty - then no modification will be performed)
      Throws:
      BadValueException - BadValueException if val is not a valid value for the specified attribute type
      Since:
      14.6
      See Also:

    • set

      public void set(AttributeType at, Collection<String> vals) throws BadValueException
      Modify attribute by setting string values.After the apply operation the attribute type will have the values specified and existing values be removed
      Parameters:
      at - attribute type (not null)
      vals - values to set. If vals is null or an empty Collection, the attribute will be deleted from the entry. Any empty Strings ("") in vals are ignored.
      Throws:
      BadValueException - if values are not a valid LDAP-encoded value for attribute or if this method is being called for single-valued attributes. .

    • set

      public void set(AttributeType at, String[] vals) throws BadValueException
      Modify attribute by setting string values.After the apply operation the attribute type will have the values specified and existing values be removed
      Parameters:
      at - attribute type (not null)
      vals - values to set (if null or null, the attribute will be deleted from the entry)
      Throws:
      BadValueException - if values are not a valid LDAP-encoded value for attribute or if this method is being called for single-valued attributes. .

    • add

      public void add(AttributeType at, Collection<String> vals) throws BadValueException
      Modify attribute by adding string values.Values that already exist, will be ignored.
      Parameters:
      at - attribute type (not null)
      vals - values to set. If vals is null or an empty Collection, then no modification will be performed). Any empty Strings ("") inside vals are ignored.
      Throws:
      BadValueException - if values are not a valid LDAP-encoded value for attribute or if this method is being called for single-valued attributes.

    • add

      public void add(AttributeType at, String[] vals) throws BadValueException
      Modify attribute by adding string values.Values that already exist, will be ignored.
      Parameters:
      at - attribute type (not null)
      vals - values to set (may be null or empty - then no modification will be performed)
      Throws:
      BadValueException - if values are not a valid LDAP-encoded value for attribute.

    • delete

      public void delete(AttributeType at, Collection<String> vals) throws BadValueException
      Modify attribute by deleting string values. The values that exist in the existing entry will be removed and others would be ignored
      Parameters:
      at - attribute type (not null)
      vals - values to set. If vals is null, or an empty Collection, then no modification will be performed. Any empty Strings ("") inside vals are ignored.
      Throws:
      BadValueException - if values are not a valid LDAP-encoded value for attribute or if this method is being called for single-valued attributes.

    • delete

      public void delete(AttributeType at, String[] vals) throws BadValueException
      Modify attribute by deleting string values.The values that exist in the existing entry will be removed and others would be ignored
      Parameters:
      at - attribute type (not null)
      vals - values to set (if null or empty - then no modification will be performed)
      Throws:
      BadValueException - if values are not a valid LDAP-encoded value for attribute.

    • setBin

      public void setBin(AttributeType at, Collection<byte[]> vals) throws BadValueException
      Modify attribute by setting binary values. After the apply operation the attribute type will have the value specified.
      Parameters:
      at - attribute type (not null)
      vals - values to set (if null or empty - the attribute will be deleted)
      Throws:
      BadValueException - BadValueException if val is not a valid value for the specified attribute type or if this method is being called for single-valued attributes.
      Since:
      14.6
      See Also:

    • setBer

      public void setBer(AttributeType at, Collection<byte[]> vals) throws BadValueException
      Modify attribute by setting BER values. After the apply operation the attribute type will have the values specified and existing values be removed
      Parameters:
      at - attribute type (not null)
      vals - values to set (if null or empty - then the attribute would be deleted)
      Throws:
      BadValueException - BadValueException if val is not a valid value for the specified attribute type or if this method is being called for single-valued attributes.
      Since:
      14.6
      See Also:

    • addBin

      public void addBin(AttributeType at, Collection<byte[]> vals) throws BadValueException
      Modify attribute by adding binary values.Values that already exist, will be ignored.
      Parameters:
      at - attribute type (not null)
      vals - values to set (if null or empty - then no modification will be performed)
      Throws:
      BadValueException - BadValueException if val is not a valid value for the specified attribute typeor if this method is being called for single-valued attributes.
      Since:
      14.6
      See Also:

    • addBer

      public void addBer(AttributeType at, Collection<byte[]> vals) throws BadValueException
      Modify attribute by adding BER values.Values that already exist, will be ignored.
      Parameters:
      at - attribute type (not null)
      vals - values to set (if null or empty - then no modification will be performed)
      Throws:
      BadValueException - BadValueException if val is not a valid value for the specified attribute type or if this method is being called for single-valued attributes.
      Since:
      14.6
      See Also:

    • deleteBin

      public void deleteBin(AttributeType at, Collection<byte[]> vals) throws BadValueException
      Modify attribute by deleting binary values. On apply only the value will be deleted if it exists and no action would be taken if it does not exist
      Parameters:
      at - attribute type (not null)
      vals - values to set (if null or empty - then no modification will be performed)
      Throws:
      BadValueException - BadValueException if val is not a valid value for the specified attribute type or if this method is being called for single-valued attributes.
      Since:
      14.6
      See Also:

    • deleteBer

      public void deleteBer(AttributeType at, Collection<byte[]> vals) throws BadValueException
      Modify attribute by deleting BER values. On apply the values that exist in the existing entry would be deleted while no action would be taken for the ones that don't exist.
      Parameters:
      at - attribute type (not null)
      vals - values to set (if null or empty - then no modification will be performed)
      Throws:
      BadValueException - BadValueException if val is not a valid value for the specified attribute type or if this method is being called for single-valued attributes.
      Since:
      14.6
      See Also:

    • set

      public void set(Attribute attr)
      Set values from given attribute. After the apply operation the attribute type will have the values specified and existing values be removed
      Parameters:
      attr - attribute (should not be null)

    • add

      public void add(Attribute attr)
      Add values from given attribute. Values that already exist, will be ignored.

      For a single valued attribute in the EntryWriter object, this function could be called multiple times. The first time it would add the attribute if it didn't exist in its copy yet; the subsequent times it would update its copy of the attribute value.

      Parameters:
      attr - attribute (should not be null)

    • delete

      public void delete(AttributeType attrType)
      Delete the attribute and all its values from the entry if it exists.
      Parameters:
      attrType - attribute type
      Since:
      15.0

    • delete

      public void delete(Attribute attr)
      Delete the attribute and the values specified in the attribute value field of the attribute. If it is empty then all values would be deleted on apply
      Parameters:
      attr - attribute

    • hasBeenApplied

      public boolean hasBeenApplied()
      Determine if the changes have already been applied
      Returns:
      true if the changes have been applied and false otherwise

    • apply

      public String apply(DirectorySession ds, CommonArgs ca) throws DSAPIException
      Apply changes to the directory. If directory session is not specified then it just simulates operation allowing to get report of performed directory operations.

      For real directory operation (when ds!=null) this method can be called only once as for Entry modification it would have no effect for next calls and impossible for renaming operation. So make sure that this methods gets called with non-null directory sessions only when changes have not been applied by using the method hasBeenApplied()

      For ds==null no operation will be performed on directory but whole process will be simulated in order to generate operations report only (This functionality is used by toString() method

      Parameters:
      ds - directory session (may be null - for getting report only)
      ca - common arguments (may be null)
      Returns:
      operation report
      Throws:
      DSAPIException
      See Also:

    • toString

      public String toString()
      Return user friendly report of planned entry modifications which will be performed by apply(DirectorySession, CommonArgs) method
      Overrides:
      toString in class Object

    • entryHasChanges

      public boolean entryHasChanges()
      Determines if there are any changes pending to be committed to the directory for an existing entry.

      This method should only be used when the object of this class has been created to modify an existing entry. This must not be invoked when the object of this class has been created with a null entry,for example,for creating or renaming or relocation operations.

      If you know the attribute types that could have been modified in the entry, it would be more efficient to invoke the method hasChanges(AttributeType...).

      Returns:
      TRUE if there are changes to any attributes in the entry, FALSE if there are no changes or if the class had been invoked with null old entry
      Since:
      15.0

    • hasChanges

      public boolean hasChanges(AttributeType... attributeTypes)
      Determines if there are any changes pending to be committed to the directory for the given list of attribute types in an existing entry.

      This must not be invoked for create entry or rename entry or relocate operations.

      This method will look for changes in each given attribute type one by one and return TRUE as soon as it finds a change.

      If no attribute type is given, it will return FALSE.

      Parameters:
      attributeTypes - list of attribute types for which pending changes need to be determined, must not be null
      Returns:
      TRUE if there are pending changes in any attribute type in the given list, FALSE if there are no changes in any or if the class had been invoked with null old entry
      Since:
      15.0