___              _ _ ____
   /   |  __________(_|_) __ \____  _  ____  __
  / /| | / ___/ ___/ / / / / / __ \| |/_/ / / /
 / ___ |(__  ) /__/ / / /_/ / /_/ />  </ /_/ /
/_/  |_/____/\___/_/_/_____/\____/_/|_|\__, /
                                      /____/

[ Home | What is AsciiDoxy? | Getting started | Reference documentation | Examples | Contributing | Changelog | GitHub ]

Java

This is an example demonstrating documentation for a Java project. The used source code files come from the Apache Commons IO project.

This is not meant to be complete documentation. Some links in the documentation may not work due to missing documentation.
Doxygen configuration
# The OUTPUT_DIRECTORY tag is used to specify the (relative or absolute) path
# into which the generated documentation will be written. If a relative path is
# entered, it will be relative to the location where doxygen was started. If
# left blank the current directory will be used.

OUTPUT_DIRECTORY       = $(OUTPUT_DIR)

# If the GENERATE_HTML tag is set to YES, doxygen will generate HTML output
# The default value is: YES.

GENERATE_HTML          = NO

# If the GENERATE_LATEX tag is set to YES, doxygen will generate LaTeX output.
# The default value is: YES.

GENERATE_LATEX         = NO

# If the GENERATE_XML tag is set to YES, doxygen will generate an XML file that
# captures the structure of the code including all documentation.
# The default value is: NO.

GENERATE_XML           = YES

# If the JAVADOC_AUTOBRIEF tag is set to YES then doxygen will interpret the
# first line (until the first dot) of a Javadoc-style comment as the brief
# description. If set to NO, the Javadoc-style will behave just like regular Qt-
# style comments (thus requiring an explicit @brief command for a brief
# description.)
# The default value is: NO.

JAVADOC_AUTOBRIEF      = YES

# Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java or
# Python sources only. Doxygen will then generate output that is more tailored
# for that language. For instance, namespaces will be presented as packages,
# qualified scopes will look different, etc.
# The default value is: NO.

OPTIMIZE_OUTPUT_JAVA   = YES

# The FILTER_PATTERNS tag can be used to specify filters on a per file pattern
# basis. Doxygen will compare the file name with each pattern and apply the
# filter if there is a match. The filters are a list of the form: pattern=filter
# (like *.cpp=my_cpp_filter). See INPUT_FILTER for further information on how
# filters are used. If the FILTER_PATTERNS tag is empty or if none of the
# patterns match the file name, INPUT_FILTER is applied.
#
# Note that for custom extensions or not directly supported extensions you also
# need to set EXTENSION_MAPPING for the extension otherwise the files are not
# properly processed by doxygen.

FILTER_PATTERNS        = *.java="sed -E 's/@(Nullable|NonNull|CheckForNull|PossiblyNull)([[:space:]]+[[:alnum:]_])/__AT__\1__\2/g'"
AsciiDoxy directives
${language("java")}  (1)
${insert("org.apache.commons.io.FileCleaningTracker")}
${insert("org.apache.commons.io.FileDeleteStrategy")}
1 Explicitly setting the language is required for this document, because we are transcoding the same classes to Kotlin. Without setting the language, AsciiDoxy does not know whether it needs to insert the Java or Kotlin version.

FileCleaningTracker

class org.apache.commons.io.FileCleaningTracker

Keeps track of files awaiting deletion, and deletes them when an associated marker object is reclaimed by the garbage collector.

This utility creates a background thread to handle file deletion. Each file to be deleted is registered with a handler object. When the handler object is garbage collected, the file is deleted.

In an environment with multiple class loaders (a servlet container, for example), you should consider stopping the background thread if it is no longer needed. This is done by invoking the method <<,exitWhenFinished>>, typically in

javax.servlet.ServletContextListener.contextDestroyed(javax.servlet.ServletContextEvent)

or similar.

Public Methods
void track(final File, final Object)

Track the specified file, using the provided marker, deleting the file when the marker instance is garbage collected.

void track(final File, final Object, final FileDeleteStrategy)

Track the specified file, using the provided marker, deleting the file when the marker instance is garbage collected.

void track(final String, final Object)

Track the specified file, using the provided marker, deleting the file when the marker instance is garbage collected.

void track(final String, final Object, final FileDeleteStrategy)

Track the specified file, using the provided marker, deleting the file when the marker instance is garbage collected.

int getTrackCount()

Retrieve the number of files currently being tracked, and therefore awaiting deletion.

List<String> getDeleteFailures()

Return the file paths that failed to delete.

synchronized void exitWhenFinished()

Call this method to cause the file cleaner thread to terminate when there are no more objects being tracked for deletion.

Members

void track(final File file,
           final Object marker)

Track the specified file, using the provided marker, deleting the file when the marker instance is garbage collected.

The normal deletion strategy will be used.

Parameters
final File file

the file to be tracked, not null

final Object marker

the marker object used to track the file, not null

Throws
NullPointerException

if the file is null

 
void track(final File file,
           final Object marker,
           final FileDeleteStrategy deleteStrategy)

Track the specified file, using the provided marker, deleting the file when the marker instance is garbage collected.

The specified deletion strategy is used.

Parameters
final File file

the file to be tracked, not null

final Object marker

the marker object used to track the file, not null

final FileDeleteStrategy deleteStrategy

the strategy to delete the file, null means normal

Throws
NullPointerException

if the file is null

 
void track(final String path,
           final Object marker)

Track the specified file, using the provided marker, deleting the file when the marker instance is garbage collected.

The normal deletion strategy will be used.

Parameters
final String path

the full path to the file to be tracked, not null

final Object marker

the marker object used to track the file, not null

Throws
NullPointerException

if the path is null

 
void track(final String path,
           final Object marker,
           final FileDeleteStrategy deleteStrategy)

Track the specified file, using the provided marker, deleting the file when the marker instance is garbage collected.

The specified deletion strategy is used.

Parameters
final String path

the full path to the file to be tracked, not null

final Object marker

the marker object used to track the file, not null

final FileDeleteStrategy deleteStrategy

the strategy to delete the file, null means normal

Throws
NullPointerException

if the path is null

 
int getTrackCount()

Retrieve the number of files currently being tracked, and therefore awaiting deletion.

Returns
int

the number of files being tracked

 
List<String> getDeleteFailures()

Return the file paths that failed to delete.

Since

2.0

Returns
List<String>

the file paths that failed to delete

 
synchronized void exitWhenFinished()

Call this method to cause the file cleaner thread to terminate when there are no more objects being tracked for deletion.

In a simple environment, you don’t need this method as the file cleaner thread will simply exit when the JVM exits. In a more complex environment, with multiple class loaders (such as an application server), you should be aware that the file cleaner thread will continue running even if the class loader it was started from terminates. This can constitute a memory leak.

For example, suppose that you have developed a web application, which contains the commons-io jar file in your WEB-INF/lib directory. In other words, the FileCleaner class is loaded through the class loader of your web application. If the web application is terminated, but the servlet container is still running, then the file cleaner thread will still exist, posing a memory leak.

This method allows the thread to be terminated. Simply call this method in the resource cleanup code, such as

javax.servlet.ServletContextListener.contextDestroyed(javax.servlet.ServletContextEvent)

  1. Once called, no new objects can be tracked by the file cleaner.

FileDeleteStrategy

class org.apache.commons.io.FileDeleteStrategy

Strategy for deleting files.

There is more than one way to delete a file. You may want to limit access to certain directories, to only delete directories if they are empty, or maybe to force deletion.

This class captures the strategy to use and is designed for user subclassing.

Since

1.3

Public Constants
FileDeleteStrategy NORMAL

The singleton instance for normal file deletion, which does not permit the deletion of directories that are not empty.

FileDeleteStrategy FORCE

The singleton instance for forced file deletion, which always deletes, even if the file represents a non-empty directory.

Public Methods
void delete(final File)

Deletes the file object, which may be a file or a directory.

boolean deleteQuietly(final File)

Deletes the file object, which may be a file or a directory.

String toString()

Gets a string describing the delete strategy.

Protected Constructors
FileDeleteStrategy(final String)

Restricted constructor.

Protected Methods
boolean doDelete(final File)

Actually deletes the file object, which may be a file or a directory.

Members

FileDeleteStrategy NORMAL

The singleton instance for normal file deletion, which does not permit the deletion of directories that are not empty.

FileDeleteStrategy FORCE

The singleton instance for forced file deletion, which always deletes, even if the file represents a non-empty directory.

void delete(final File fileToDelete)

Deletes the file object, which may be a file or a directory.

If the file does not exist, the method just returns.

Subclass writers should override doDelete(File), not this method.

Parameters
final File fileToDelete

the file to delete, not null

Throws
NullPointerException

if the file is null

IOException

if an error occurs during file deletion

 
boolean deleteQuietly(final File fileToDelete)

Deletes the file object, which may be a file or a directory.

All IOExceptions are caught and false returned instead. If the file does not exist or is null, true is returned.

Subclass writers should override doDelete(File), not this method.

Parameters
final File fileToDelete

the file to delete, null returns true

Returns
boolean

true if the file was deleted, or there was no such file

 
String toString()

Gets a string describing the delete strategy.

Returns
String

a string describing the delete strategy

 
FileDeleteStrategy(final String name)

Restricted constructor.

Parameters
final String name

the name by which the strategy is known

 
boolean doDelete(final File fileToDelete)

Actually deletes the file object, which may be a file or a directory.

This method is designed for subclasses to override. The implementation may return either false or an IOException when deletion fails. The delete(File) and deleteQuietly(File) methods will handle either response appropriately. A check has been made to ensure that the file will exist.

This implementation uses <<,File#delete()>>.

Parameters
final File fileToDelete

the file to delete, exists, not null

Returns
boolean

true if the file was deleted

Throws
NullPointerException

if the file is null

IOException

if an error occurs during file deletion
AsciiDoxy