ARROW-15958: [Java][Docs] Improve and document StackTrace

[lidavidm]

This can be useful to identify the origin of a leaked buffer.

While there's a "public" API, it wasn't actually usable because it has a parameter of package-private type. This adds an overload that doesn't take that parameter so the API is actually usable.

[github-actions]

https://issues.apache.org/jira/browse/ARROW-15958

[lidavidm]

CC @davisusanibar

[pitrou]

Should we move this forward? @lwhite1 Could you take a look?

[davisusanibar]

This is really useful at closed with outstanding buffers allocated.

Could it be possible to show this error log if -Darrow.memory.debug.allocator=true is enabled? It means get this log implicitly and not needed to call print method?

[lidavidm]

This already happens if you enable the TRACE log level for org.apache.arrow.memory.BaseAllocator. I'll update the docs with an example.

[lwhite1]

Looks good to me

[lidavidm]

I'll open PRs to bump the timeout on the docs build (looks like we're getting close to the current 30 minutes) and fix some of those Sphinx warnings I'm seeing

/arrow/docs/source/developers/experimental_repos.rst:21: WARNING: duplicate label experimental-repos, other instance in /arrow/docs/source/developers/experimental_repos.rst
/arrow/docs/source/python/integration/python_java.rst:445: WARNING: Inline interpreted text or phrase reference start-string without end-string.
WARNING: don't know which module to import for autodocumenting 'BufferReader' (try placing a "module" or "currentmodule" directive in the document, or giving an explicit module name)
WARNING: don't know which module to import for autodocumenting 'BufferWriter' (try placing a "module" or "currentmodule" directive in the document, or giving an explicit module name)
WARNING: don't know which module to import for autodocumenting 'Context' (try placing a "module" or "currentmodule" directive in the document, or giving an explicit module name)
WARNING: don't know which module to import for autodocumenting 'CudaBuffer' (try placing a "module" or "currentmodule" directive in the document, or giving an explicit module name)
WARNING: don't know which module to import for autodocumenting 'HostBuffer' (try placing a "module" or "currentmodule" directive in the document, or giving an explicit module name)
WARNING: don't know which module to import for autodocumenting 'IpcMemHandle' (try placing a "module" or "currentmodule" directive in the document, or giving an explicit module name)
WARNING: don't know which module to import for autodocumenting 'new_host_buffer' (try placing a "module" or "currentmodule" directive in the document, or giving an explicit module name)
WARNING: don't know which module to import for autodocumenting 'read_message' (try placing a "module" or "currentmodule" directive in the document, or giving an explicit module name)
WARNING: don't know which module to import for autodocumenting 'read_record_batch' (try placing a "module" or "currentmodule" directive in the document, or giving an explicit module name)
WARNING: don't know which module to import for autodocumenting 'serialize_record_batch' (try placing a "module" or "currentmodule" directive in the document, or giving an explicit module name)
...
arrow/docs/source/cpp/api/flight.rst:207: WARNING: doxygenfile: Cannot find file "arrow/flight/transport_impl.h
/arrow/docs/source/cpp/api/support.rst:79: WARNING: doxygenstruct: Cannot find class "arrow::ArrowGlobalOptions" in doxygen xml output for project "arrow_cpp" from directory: ../../cpp/apidoc/xml
looking for now-outdated files... none found
pickling environment... done
checking consistency... done
preparing documents... done
/arrow/docs/source/format/Versioning.rst:21: WARNING: unknown document: status
/arrow/docs/source/java/cdata.rst:30: WARNING: unknown document: ../python/integration/python_java.rst
/arrow/docs/source/java/cdata.rst:40: WARNING: unknown document: ../developers/cpp/building.rst
/arrow/docs/source/status.rst:22: WARNING: unknown document: versioning