search

vaadin / docs

Official documentation for Vaadin and Hilla.
https://vaadin.com/docs
Other
29 stars 196 forks source link

Document Lookup/Instantiator #739

Open mvysny opened 3 years ago

mvysny commented 3 years ago

There is no documentation for custom Lookup/Instantiator. Trying to implement one is a series of try-and-fail, steps, missteps, going through crappy outdated javadoc etc. Absolutely no mention of instantiator/lookup in the documentation. This is completely ridiculous.

Vaadin 20.

For example, if I want to implement a custom Instantiator for Dagger DI:

  1. I go to the Instantiator class and learn that the Java ServiceLoader is used. That is not true: javadoc of init() says that InstantiatorFactory is used.
  2. The InstantiatorFactory javadoc says absolutely nothing about how it is being created, and how I can force Vaadin to use a custom one.
  3. The VaadinService.loadInstantiators() sources finally reveals that the Lookup class is used, to load InstantiatorFactory and produce an Instantiator.
  4. I now have no idea what is the correct way to go: should I provide a custom Lookup which is able to provide InstantiatorFactory, or should I rather override VaadinService.loadInstantiators()? What is the best practice here?
  5. Say that I want to be a good citizen and provide my own Lookup interface. How should I do it? The Lookup javadoc doesn't mention at all, how exactly I can provide a custom implementations of Lookup. I try to analyze sources for LookupInitializer which contain more of abstract shit, ultimately giving up and giving Lookup the finger.
  6. Overriding VaadinService and providing custom impl of loadInstantiators() is much easier - it doesn't feel right but I don't care at this point - I'm pissed off since I wasted a lot of time and I need to move forward with this shit.
  7. How should I now implement the Instantiator? Should I extend something or delegate to something or implement from scratch? Should I delegate to DefaultInstantiator? Not easy: https://github.com/vaadin/flow/issues/8427 and it's NOT DOCUMENTED. If I start implementing that shit from scratch, is it okay if I return null for getI18nProvider()? What about getServiceInitListeners(), how to implement that?

I feel MAD about having to go through all of the above. There are countless abstractions, no simplicity at all, absolute mess of interfaces, loaders and whatnot. Fighting for simplicity, yeah right.

OlliTietavainenVaadin commented 2 years ago

The mechanism can be found from here: https://mvysny.github.io/vaadin-custom-instantiator/

jouni commented 2 years ago

I’m quite out of my comfort zone with this topic, but from what I gather, there are some issues in the JavaDocs. @mshabarov, could you take a look into those, if there’s incorrect documentation there?