[
https://issues.apache.org/jira/browse/SOLR-12309?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16480691#comment-16480691
]
Jason Gerlowski commented on SOLR-12309:
----------------------------------------
bq. I'm curious why the no-arg constructor and the fluent methods for providing
the ZK definition were deprecated.
Pre SOLR-11629, a new SolrJ user could type {{new
CloudSolrClient.Builder().build()}}, and wouldn't have an inkling that was
wrong until they went to run or test their app and got an IllegalStateException
and a so-so error message. So Varun thought (and I agreed): if we could get
users that correcting information sooner by enforcing it at compile time, then
why wouldn't we? Isn't the more intuitive API the one that's harder to take
mis-steps with?
In short: A 100% fluent API nudges users towards "Runtime Exception Driven
Development" when some subset of the {{with*}} APIs are actually mandatory.
That said: I'm not against the fluent API in general. In fact, I added most of
it back in the day. But it's not the best way to handle arguments that are
either (1) required, or (2) are mutually exclusive with another argument. And
Solr URL/ZK-string args fall into both of these categories.
To get back to things I think we're already in agreement on though, I see your
points about what's missing from the Javadocs for these constructors. I took
familiarity with java.util.Optional for granted, which was a mistake. And some
examples would go a long way. (Particularly one with {{Optional.empty()}} as
the chroot). I'll attach some Javadocs this weekend that hopefully improve
things.
> CloudSolrClient.Builder constructors are not well documented
> ------------------------------------------------------------
>
> Key: SOLR-12309
> URL: https://issues.apache.org/jira/browse/SOLR-12309
> Project: Solr
> Issue Type: Bug
> Security Level: Public(Default Security Level. Issues are Public)
> Components: clients - java
> Affects Versions: 7.3
> Reporter: Shawn Heisey
> Assignee: Jason Gerlowski
> Priority: Minor
>
> I was having a lot of trouble figuring out how to create a CloudSolrClient
> object without using deprecated code.
> The no-arg constructor on the Builder object is deprecated, and the two
> remaining methods have similar signatures to each other. It is not at all
> obvious how to successfully call the one that uses ZooKeeper to connect. The
> javadoc is silent on the issue. I did finally figure it out with a lot of
> googling, and I would like to save others the hassle.
> I believe that this is what the javadoc for the third ctor should say:
> ----
> Provide a series of ZooKeeper hosts which will be used when configuring
> CloudSolrClient instances. Optionally, include a chroot to be used when
> accessing the ZooKeeper database.
> Here are a couple of examples. The first one has no chroot, the second one
> does:
> new CloudSolrClient.Builder(zkHosts, Optional.empty())
> new CloudSolrClient.Builder(zkHosts, Optional.of("/solr"))
> ----
> The javadoc for the URL-based method should probably say something to
> indicate that it is easy to confuse with the ZK-based method.
> I have not yet looked at the current reference guide to see if that has any
> clarification.
> Is it a good idea to completely eliminate the ability to create a cloud
> client using a single string that matches the zkHost value used when starting
> Solr in cloud mode?
--
This message was sent by Atlassian JIRA
(v7.6.3#76005)
---------------------------------------------------------------------
To unsubscribe, e-mail: [email protected]
For additional commands, e-mail: [email protected]
