...

The following public interface will be changed, adding methods with extra arguments for join on foreign key and deprecating the method calls with a single materialization option:

• org/apache/kafka/streams/kstream/KTable

...

As discussed in the mail list, there are two changes: a bug-fix and a new feature to replace deprecated method.

Bug-fix: 

Whenever invoking methods that perform join on foreign key, the subscription-store created under-the-hood will use the same materialization method as parameter provided as "materialized".

This means that, if the materialized parameter has a in-memory store, the subscriptions store will also be in-memory.

New Feature / Deprecation:

The new feature proposal consists on adding the following methods on KTable interface (and implementing them in KtableImpl.java):

...

                               final Materialized<KO, V, KeyValueStore<Bytes,byte[]> subscriptionStoreMaterialization);

The following method calls will be deprecated, since a user that is providing the materialization method of a table-store will likely also be deciding on the materialization method of a  subscriptions-store

<VR, KO, VO> KTable<K, VR> leftJoin(final KTable<KO, VO> other,

                                    final Function<V, KO> foreignKeyExtractor,

                                    final ValueJoiner<V, VO, VR> joiner,

                                    final Named named,

                                    final Materialized<K, VR, KeyValueStore<Bytes, byte[]>> materialized);

<VR, KO, VO> KTable<K, VR> leftJoin(final KTable<KO, VO> other,

                                    final Function<V, KO> foreignKeyExtractor,

                                    final ValueJoiner<V, VO, VR> joiner,

                                    final Materialized<K, VR, KeyValueStore<Bytes, byte[]>> materialized);

<VR, KO, VO> KTable<K, VR> join(final KTable<KO, VO> other,

                                final Function<V, KO> foreignKeyExtractor,

                                final ValueJoiner<V, VO, VR> joiner,

                                final Named named,

                                final Materialized<K, VR, KeyValueStore<Bytes, byte[]>> materialized);

<VR, KO, VO> KTable<K, VR> join(final KTable<KO, VO> other,

                                final Function<V, KO> foreignKeyExtractor,

                                final ValueJoiner<V, VO, VR> joiner,

                                final Materialized<K, VR, KeyValueStore<Bytes, byte[]>> materialized);

As discussed in the mail-list, the reason to allow this kind of fine-grain tuning are:

...

The bug-fix modification may change legacy code behaviour when updated to newer version of Kafka streams, specially when the materialized parameter is in-memory and the subscription-store grows too big (since it will not be stored in disk anymore as the old API did, but in-memory too instead). This scenario would require to add comments about this change of behaviour in the update documentation and perform it in a non-minor release.

New Feature

...

+ Deprecation:

Four API methods will be deprecated and replaced for four new equivalent methods. After the deprecation period expires, the new API will require users who use those kafka-streams methods to update their code. 

...

It’s an addition to the API instead of a change on a previous API section. Any other change is likely going to be in private methods - not breaking API compatibility and keeping behaviour.

Rejected Alternatives

• Only piggybacking on the Materialization provided by the materialized parameter. It would limit the desired customisation possibilities to the user.
• Creating a specific class for subscription-stores Materialization - it would increase the API footprint without bringing and code complexity without a good trade-off.
• Not deprecating the previous API. As agreed on the discussion, a user that is concerned about the materialization method of a table-store is likely concerned with the materialization method of subscription store. 
• Bug-fix: since the old API call is being deprecated, users that would be interested on avoiding the opinionated storage should instead use the new API.