+1 for placing the AdminClient in a separate package. I have several dozen applications that use kafka-clients.jar to produce/consume, and those applications don't have a need for the AdminClient. And, it's probably better not to have the AdminClient methods available in those applications from a management standpoint.
Right now I only have one application that uses the internal scala AdminClient (from Java), and that's for ops and monitoring purposes. I'll refactor that app to use the Java native client once it's available. I use AdminClient.describeGroup(groupId), which doesn't look like it's making the cut, so I'll look to extend the client or send a pull request. Bill On Tue, Feb 7, 2017 at 6:27 PM, Gwen Shapira <g...@confluent.io> wrote: > Ismael raised the concern (offline) that even if we mark the API as > unstable, people will use it right away because it is so valuable. So > we'll have trouble changing later if we prefer a different API. > > I agree, but since I still prefer to experiment a bit "in the wild", I > suggested placing the AdminClient in its own Maven package (separate > from kafka-clients). This will allow users to upgrade their > AdminClient dependency when they want to, without worrying about being > stuck with an older producer/consumer version at the same time. It > should give us better ability to experiment since users can stay on > the older APIs as long as they want. > > IMO, we can leave the packages separate forever and avoid pains of > merging them. Does anyone see downsides to separate packages? > > On Tue, Feb 7, 2017 at 4:17 PM, Gwen Shapira <g...@confluent.io> wrote: > >>> - Personally I don't think splitting the admin methods up actually > makes > >>> things more usable. It just makes you have to dig through our > >>> hierarchy. I > >>> think a flat class with a bunch of operations (like the consumer > api) is > >>> probably the easiest for people to grok and find things on. I am > kind > >>> of a > >>> dumb PHP programmer at heart, though. > >>> > >> > >> I am not sure it's fair to compare the AdminClient with the Consumer. > The > >> former has APIs for a bunch of unrelated APIs (topics, ACLs, configs, > >> consumer groups, delegation tokens, preferred leader election, partition > >> reassignment, etc.) where the latter is pretty specialised. For each of > the > >> resources, you may have 3-4 operations, it will get confusing fast. > Also, > >> do you really think an API that has one level of grouping will mean that > >> users have to "dig through our hierarchy"? Or are you concerned that > once > >> we go in that direction, there is a danger of making the hierarchy more > >> complicated? > >> > >> Finally, I am not sure I would use the consumer as an example of > something > >> that is easy to grok. :) The fact that methods behave pretty differently > >> (some are blocking while others only have an effect after poll) with no > >> indication from the type signature or naming convention makes it harder, > >> not easier, to understand. > > > > > > I also wouldn't consider the consumer a shining example of usability. > > > > Streams went in the "split stuff" direction. At the upper level, you > > can either create a Stream or a Table. Then you have relevant methods > > under each. They even have a bit more hierarchy: GroupedStream under > > stream where aggregates live. I thought it works rather well once you > > figure out the rules. > > > > But I think there is a class of engineers who learn how to use a > > client by creating an instance in IntelliJ and then browse through the > > list of methods available and see what looks right. Hierarchies throw > > us off a bit off. I remember browsing KStream and freaking out because > > I can't find "aggregate" method. So we need to make sure this thing > > makes sense to new users (we can find a few to test on?). > > > > Since moving stuff around a hierarchy is fairly easy, why not try one > > way, leave things as "unstable" for one release and gather feedback? > > We usually get usability complaints fairly fast. > > > >> > >> Ismael > > > > > > > > -- > > Gwen Shapira > > Product Manager | Confluent > > 650.450.2760 | @gwenshap > > Follow us: Twitter | blog > > > > -- > Gwen Shapira > Product Manager | Confluent > 650.450.2760 | @gwenshap > Follow us: Twitter | blog >
