DirTree Chilkat2 Java Reference Documentation

DirTree

Current Version: 11.7.0

Markdown version of this page for AI tools (v 11.7.0) · all AI docs

Chilkat.DirTree

Iterate through files and subdirectories under a base directory.

Chilkat.DirTree is a lightweight directory-tree iterator for traversing files and subdirectories under a selected base directory. It supports recursive and non-recursive traversal and exposes useful information about the current item, including absolute path, UNC path, relative path, file size, and whether the current item is a directory.

Directory traversal

Iterate through the contents of a base directory, either recursively or one level at a time.

Current-item details

Get the current item's full path, relative path, UNC path, size, and directory/file status.

Recursive scanning

Traverse entire directory trees when an application needs to process all nested files and folders.

Non-recursive listing

Limit iteration to the immediate contents of the base directory when deeper traversal is not needed.

Path-friendly output

Use absolute or relative paths depending on whether the application needs filesystem access or archive-style relative names.

Error-aware iteration

Use DoneIterating to distinguish normal completion from an error when an iteration method returns false.

Common pattern: Set the base directory and recursion behavior, begin iterating, process each current item using the path and metadata properties, then check DoneIterating when iteration stops to determine whether traversal completed normally or ended because of an error.

For an extended overview, see DirTree Class Overview.

Object Creation

import com.chilkatsoft.chilkat2.ChilkatException;
import com.chilkatsoft.chilkat2.DirTree;

try (DirTree dirTree = new DirTree()) {
    // ... use dirTree ...
} catch (ChilkatException e) {
    System.out.println(e.getMessage());          // "DirTree.someMethod failed: <reason>"
    System.out.println(e.getLastErrorText());    // the full log of the failed call
}

public DirTree()

Creates the underlying native Chilkat object. The native library (chilkat2java) is loaded the first time any Chilkat2 object is created; see the README in the download for where it is looked for (-Dchilkat2.library.path, a classpath resource, or java.library.path).

public void close()

Releases the native object (DirTree is AutoCloseable, so try-with-resources calls it). Calling it again does nothing; any other method or property accessor called afterwards throws IllegalStateException. An object that is never closed is freed by a background cleaner once it becomes unreachable, but the garbage collector does not see native memory, so closing is the normal path. Objects returned by methods are owned by the caller too.

public boolean isClosed()

Returns true once close() has been called.

Errors

A method that fails throws ChilkatException, an unchecked exception carrying getClassName(), getMethodName(), getReason() (one line, also in the message) and getLastErrorText() (the full log, captured at the moment of the failure). The object remains usable. Methods that look something up and find nothing return null instead of throwing (each such method says so), and methods that answer a question (hasMember, isUnlocked, ...) return a plain boolean. Property accessors do not throw for Chilkat reasons.

A null string or object argument throws NullPointerException naming the parameter (except where a method documents that null is accepted), and a string containing U+0000 throws IllegalArgumentException.

Use an object from one thread at a time; it may be handed from one thread to another. The one cross-thread operation is setting setAbortCurrent(true) on an object that is busy in another thread (on the classes that have AbortCurrent). Unlocking: call new Global().unlockBundle("...") once at startup.

Properties

BaseDir

// read/write
String getBaseDir()
void setBaseDir(String value)

Specifies the root directory whose contents are traversed. Set this property before calling BeginIterate.

The value may be an absolute filesystem path or a relative path. A relative path is resolved from the calling process's current working directory.

Iteration scope: The iterator visits the files and subdirectories contained under this directory. The Recurse property determines whether nested levels are included.

More Information and Examples

Iterate over Files and Directories in Filesystem Directory Tree

Method result	`DoneIterating`	Meaning
`false`	`true`	The directory was empty, or the last item has been passed. This is normal completion.
`false`	`false`	An error occurred. Examine `LastErrorText`.

`true`	Visit files and directories throughout the complete tree rooted at `BaseDir`.
`false`	Visit only the immediate contents of `BaseDir`.

Return value	`DoneIterating`	Meaning
`true`	`false`	The iterator advanced successfully and a current item is available.
`false`	`true`	The last item has been passed; traversal completed normally.
`false`	`false`	An error occurred. Examine `LastErrorText`.

Return value	`DoneIterating`	Meaning
`true`	`false`	The first item is available.
`false`	`true`	The directory contains no items in the selected traversal scope. This is not an error.
`false`	`false`	Initialization failed. Examine `LastErrorText`.

DirTree Chilkat2 Java Reference Documentation

DirTree

Current Version: 11.7.0

Iterate through files and subdirectories under a base directory.

Directory traversal

Current-item details

Recursive scanning

Non-recursive listing

Path-friendly output

Error-aware iteration

Object Creation

Errors

Properties

BaseDir

DebugLogFilePath

DoneIterating

FileSize32

FileSize64

FileSizeStr

FullPath

FullUncPath

IsDirectory

LastErrorHtml

LastErrorText

LastErrorXml

LastMethodSuccess

Recurse

RelativePath

UncommonOptions

VerboseLogging

Version

Methods

AdvancePosition

BeginIterate