[
https://issues.apache.org/jira/browse/SOLR-12309?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16465984#comment-16465984
]
Shawn Heisey commented on SOLR-12309:
-------------------------------------
I'm not saying that the use of Optional was bad. Just that I couldn't figure
it out how to use it by looking at the Builder javadoc. I had to go searching
for docs on Optional -- it was a object type I had never encountered before. I
suspect that this will be relatively common.
A java developer gets to know the more basic objects really quickly and they
become second nature. Things like Optional are not so common. Of course we
can't provide documentation for EVERY native object we use, but when we use
something outside what developers use every day, we ought to provide some
simple examples.
At first I just tried a List<String> with the individual zkHost values in it,
which naturally failed, because it tried to interpret those strings as URLs. I
hadn't even quite noticed that the URL-based constructor was there when I did
this. I was using my IDE's language-specific capabilities to find the
constructor, not reading the javadocs directly. When I did a closer
examination of the javadoc after that trial didn't work, I saw my mistake, but
still didn't know how to actually create an Optional object to use the correct
constructor.
I think I did try "null" for the Optional argument. If I did, I don't remember
what the error for that was. I can see what it does.
The Optional could have been replaced with a simple String value to
differentiate it from the URL-based constructor. Most java developers already
know how to deal with String.
I'm curious why the no-arg constructor and the fluent methods for providing the
ZK definition were deprecated. The Fluent paradigm that the builders use is
pretty straightforward and still present, so that still seems like a relevant
way to use the builder.
> 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
> 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]
