add withCachedTypes to HollowConsumer.Builder

[ghost]

Almost all of the wiring was in place to pass a list of cached types,
just that there were no builder methods.

See https://hollow.how/advanced-topics/#caching for an overview of the
feature.

[PaulSandoz]

I think we need to specify this more clearly with regards to the client API. POJO is more of a producer term.

Jotting down some notes.

In this case we are referring to hollow records and the choice between using the HollowObjectFactoryProvider when caching is not enabled and the HollowObjectCacheProvider when caching is enabled. Such choice is performed by the generated API class (i.e. see HollowConsumer.Builder.withGeneratedAPIClass) which is instantiated by the HollowConsumer with the cached types, if any.

The generated API class will use one of the factories, HollowObjectFactoryProvider or HollowObjectCacheProvider (the latter effectively uses the former) to instantiate an instance of a HollowRecord for the type and cache it. The concrete type of the HollowRecord instance will be the generated API class associated with the type.

When an instance of a type is returned from the client API, for example lookup given its ordinal or via a search using an index, the factory will be used. When caching is enabled the same HollowRecord instance of a type will always be returned for a given ordinal (even if the consumer refreshes, assuming the ordinal has not been removed). (The caching is not sophisticated, such as using a LRU to keep the top N accessed records, perhaps using with soft references.)

Caching may be disabled by calling the detachCaches method on the generated API (although once disabled it cannot be re-enabled).

[ghost]

I originally wrote this as extra arguments to withGeneratedAPIClass, e.g.:

public CinderConsumerBuilder withGeneratedAPIClass(
    Class<? extends HollowAPI> generatedAPIClass,
    String...cachedTypes) { ... }

Would this be preferable, @PaulSandoz? It would reinforce that the two go hand-in-hand.

[PaulSandoz]

Yes, an additional method with a varargs parameter would more closely bind the relationship.
We could make it:
withGeneratedAPIClass(Class<? extends HollowAPI> generatedAPIClass, String cacheType, String... additionalCachedTypes)
Thereby more clearly disambiguating the two method.

[ghost]

Related to #380 in the sense that users of the HollowConsumer API never had a chance to enable caching and thus never exposed to the thread safety issues. We may have seen issues caused by this within Netflix where we use lower-level APIs to enable the caching.