GH-37889: [Java][Doc] Improve JDBC driver documentation

[jduo]

Rationale for this change

Correct inaccuracies and better document how to connect with the Flight SQL JDBC Driver.

What changes are included in this PR?

• Correct the user property.
• Correct the default for useEncryption.
• Elaborate on using the Properties object when connecting and describe the order of precedence.

Are these changes tested?

N/A

Are there any user-facing changes?

Yes

• Closes: [Java][Docs] JDBC Arrow Flight SQL Driver documentation #37889

[github-actions]

⚠️ GitHub issue #1115 has been automatically assigned in GitHub to PR creator.

[github-actions]

⚠️ GitHub issue #37899 has no components, please add labels for components.

[jduo]

@lidavidm @danepitkin

[adamkennedy]

Maybe discuss if this is case sensitive? When I was setting up DBeaver, all the other major parameters were in the form FOO_BAR, and this one is documented as fooBar

[jduo]

Hmm, all parameters should be camelCase per:

arrow/java/flight/flight-sql-jdbc-core/src/main/java/org/apache/arrow/driver/jdbc/utils/ArrowFlightConnectionConfigImpl.java

Line 168 in 547b240

public enum ArrowFlightConnectionProperty implements ConnectionProperty {

and

arrow/java/flight/flight-sql-jdbc-core/src/main/java/org/apache/arrow/driver/jdbc/utils/ArrowFlightConnectionConfigImpl.java

Line 202 in 547b240

Object value = properties.get(camelName);

Though the get() implementation seems to also allow fully lower-case. It's probably supposed to be case-insensitive though.

[lidavidm]

Let's explicitly document whether it's case-sensitive or not, and maybe we can split out a separate ticket to make it case-insensitive if needed

[jduo]

I've documented that names are case-sensitive for simplicity's sake.

If we want to be more precise, names are case-insensitive on the connection URI (since we internally lower-case them after parsing) and case-sensitive in the Properties object, but really they should consistently be case-insensitive.

[adamkennedy]

Other than the one comment above, these fixes are helpful

[conbench-apache-arrow]

After merging your PR, Conbench analyzed the 4 benchmarking runs that have been run so far on merge-commit b42d44e.

There were no benchmark performance regressions. 🎉

The full Conbench report has more details.