Package com.isode.dsapi

Class LDIF

java.lang.Object

com.isode.dsapi.LDIF

public class LDIF
extends Object

A class which enables loading and saving of records from/to LDIF files.

Author:

jp

Constructor Summary

Constructors

Constructor	Description
LDIF(String in_fnam, String out_fnam)	Set up an LDIF stream for input and/or output with the given files.

Method Summary

Modifier and Type	Method	Description
void	close()	Close the input/output files.
static String	entryToString(GenericEntry entry)	Convert a GenericEntry to an LDIF-encoded string.
String	errors()	Return a string describing all the errors since the last call to this function, or null if there are none.
protected void	finalize()	Releases any native structures associated with this object.
GenericEntry	get()	Get the next entry from the LDIF input file.
GenericEntry	get(long offset)	Get the entry from the LDIF input file at the given file-offset, which should be a value returned by a call to tell().
boolean	getAllowUnknownAttrs()	Get the current 'allow unknown attributes' flag status.
ChangeEntry	getChange()	Get the next ChangeEntry from the LDIF input file.
Entry	getEntry()	Get the next Entry from the LDIF input file.
void	put(GenericEntry entry)	Write an entry to the LDIF output file.
void	putComment(String str)	Add a comment to the output LDIF file.
void	seek(long offset)	Re-seek the input file to the given file-offset, which should be a value previously returned by tell().
void	setAllowUnknownAttrs(boolean flag)	Set the status of the 'allow unknown attributes' flag.
long	tell()	Return the current read file-offset in the input file, which can be used later on to seek() back to this point.
String	toString()	Returns a String representation of the LDIF stream

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Details

LDIF

public LDIF(String in_fnam,
 String out_fnam)
     throws OperationFailedException,
NullPointerException,
NativeLibraryException

Set up an LDIF stream for input and/or output with the given files.

Parameters:

in_fnam - Input pathname, or null for no input

out_fnam - Output pathname, or null for no output

Throws:

OperationFailedException - Can't open/create one of the files

NullPointerException - Both arguments were null

NativeLibraryException - Internal unrecoverable error

Method Details

close

public void close()
           throws NativeLibraryException

Close the input/output files. This is done automatically when the object is finalized by Java, but the delay before this happens is unpredictable. For this reason it is better to close the file manually with this call. If any operation is attempted on the LDIF object after this call, an OperationFailedException will be thrown.

Throws:

NativeLibraryException - Internal unrecoverable error

setAllowUnknownAttrs

public void setAllowUnknownAttrs(boolean flag)

Set the status of the 'allow unknown attributes' flag. With this flag set, unknown attributes found in the LDIF file won't be rejected with an error, but will be passed back with an 'octetstring' syntax. These unknown attributes can be written over LDAP or to LDIF files, but not sent over DAP.

Parameters:

flag - Allow unknown attributes?

getAllowUnknownAttrs

public boolean getAllowUnknownAttrs()

Get the current 'allow unknown attributes' flag status.

Returns:

Allow unknown attributes?

put

public void put(GenericEntry entry)
         throws OperationFailedException,
NullPointerException,
BadEntryException,
BadDNException,
NativeLibraryException

Write an entry to the LDIF output file. Write any GenericEntry subclass instance: Entry, AddEntry, ModifyEntry, DeleteEntry or RenameEntry

Parameters:

entry - GenericEntry to write

Throws:

OperationFailedException - Error writing data to the file, or stream has been closed or was never opened for writing

NullPointerException - Argument is null

BadEntryException - The entry could not be converted to LDIF format

BadDNException - The DN could not be converted to LDIF format

NativeLibraryException - Internal unrecoverable error

get

public GenericEntry get()
                 throws OperationFailedException,
BadEntryException,
BadDNException,
NativeLibraryException

Get the next entry from the LDIF input file. End of file is indicated by a null return rather than by an exception. A GenericEntry is returned, which may be an instance of: Entry, AddEntry, ModifyEntry, DeleteEntry or RenameEntry

Returns:

GenericEntry loaded, or null for end-of-file

Throws:

OperationFailedException - Stream has been closed or was never opened for reading

BadEntryException - A bad entry on the file was encountered, which will be skipped

BadDNException - The loaded entry has a bad DN

NativeLibraryException - Internal unrecoverable error

get

public GenericEntry get(long offset)
                 throws OperationFailedException,
BadEntryException,
BadDNException,
NativeLibraryException

Get the entry from the LDIF input file at the given file-offset, which should be a value returned by a call to tell(). This does a seek() and then a get(). Following get() calls will continue on from this point in the file.

Parameters:

offset - A file-offset previously returned by tell() for this file

Returns:

GenericEntry loaded, or null for end-of-file

Throws:

OperationFailedException - Seeking to the offset was not possible, or stream has been closed or was never opened for reading

BadEntryException - A bad entry on the file was encountered, which will be skipped

BadDNException - The loaded entry had a bad DN

NativeLibraryException - Internal unrecoverable error

getEntry

public Entry getEntry()
               throws OperationFailedException,
BadEntryException,
BadDNException,
NativeLibraryException

Get the next Entry from the LDIF input file. End of file is indicated by a null return rather than by an exception. If a change-entry is read, a BadEntryException is thrown.

Returns:

Entry loaded, or null for end-of-file

Throws:

OperationFailedException - Stream has been closed or was never opened for reading

BadEntryException - A bad entry on the file was encountered, which will be skipped

BadDNException - The loaded entry has a bad DN

NativeLibraryException - Internal unrecoverable error

getChange

public ChangeEntry getChange()
                      throws OperationFailedException,
BadEntryException,
BadDNException,
NativeLibraryException

Get the next ChangeEntry from the LDIF input file. End of file is indicated by a null return rather than by an exception. If a normal entry is read, a BadEntryException is thrown. The returned value will be an instance of one of the types: AddEntry, ModifyEntry, DeleteEntry or RenameEntry.

Returns:

ChangeEntry loaded, or null for end-of-file

Throws:

OperationFailedException - Stream has been closed or was never opened for reading

BadEntryException - A bad entry on the file was encountered, which will be skipped

BadDNException - The loaded entry has a bad DN

NativeLibraryException - Internal unrecoverable error

tell

public long tell()
          throws OperationFailedException,
NativeLibraryException

Return the current read file-offset in the input file, which can be used later on to seek() back to this point.

Returns:

File-offset of input file current read position

Throws:

OperationFailedException - Stream has been closed or was never opened for reading

NativeLibraryException - Internal unrecoverable error

seek

public void seek(long offset)
          throws OperationFailedException,
NativeLibraryException

Re-seek the input file to the given file-offset, which should be a value previously returned by tell().

Parameters:

offset - File-offset previously returned by tell()

Throws:

OperationFailedException - Seeking to the offset was not possible, or stream has been closed or was never opened for reading

NativeLibraryException - Internal unrecoverable error

errors

public String errors()
              throws OperationFailedException,
NativeLibraryException

Return a string describing all the errors since the last call to this function, or null if there are none. The errors are formatted in lines terminated by '\n' characters.

Returns:

Error string, or null

Throws:

OperationFailedException - Stream has been closed

NativeLibraryException - Internal unrecoverable error

putComment

public void putComment(String str)
                throws OperationFailedException,
NativeLibraryException

Add a comment to the output LDIF file. The string may contain newlines to make a multi-line comment. The string "# " is added before each line to make it into an LDIF comment.

Parameters:

str - Comment string to write to LDIF output file

Throws:

OperationFailedException - Stream has been closed

NullPointerException - Argument is null

NativeLibraryException - Internal unrecoverable error

entryToString

public static String entryToString(GenericEntry entry)
                            throws NullPointerException,
BadEntryException,
BadDNException,
NativeLibraryException

Convert a GenericEntry to an LDIF-encoded string. The encoded string consists of lines, each of which is terminated with the platform line-separator (e.g. "\r\n" on Windows).

Parameters:

entry - GenericEntry to convert

Returns:

LDIF-encoding of the entry as a string

Throws:

NullPointerException - Argument is null

BadEntryException - The entry could not be converted to LDIF format

BadDNException - The DN could not be converted to LDIF format

NativeLibraryException - Internal unrecoverable error

finalize

protected void finalize()
                 throws Throwable

Releases any native structures associated with this object.

Overrides:

finalize in class Object

Throws:

Throwable

toString

public String toString()

Returns a String representation of the LDIF stream

Overrides:

toString in class Object

Returns:

String representation of the LDIF stream