...

/** Retrieves record metadata for a topic asynchronously. This method does not block.
 *  @param callback will be called when the records has been retrieved or has failed.
 *  @param storeName the name of the store the user is querying.
 * /
void getMetadataAsync(RecordCallback callback, String storeName);


/** Retrieves offsets. If num.threads.per.task >= 1, then it will return offsets out of order.
 *  @param inOrder the expectation for the offsets to be in order.
 *  @param storeName name of store being queried.
 *  @throws IllegalStateException if inorder == true when num.threads.per.task > 1
 */
Collections<StreamsMetadata> processMetadataForStore(boolean inOrder, String storeName);

The purpose of RecordCallback is analogous to KafkaConsumer's OffsetCommitCallback. The user would use this interface (or class?) to define the end behavior of a method.  It could be used to notify the user that they could move on to processing the next record, or it could be used as a feedback loop to send another request for the same record (if it failed).

...

There are no considerations for deprecation, particularly since we are adding a new capability, not upgrading a preexisting one. 

However, if the user calls for records expecting it to be in-order and it's not. Then an exception will be thrown notifying the client that the configs are incompatible with their method request.

For example, the original metadataForStore method will call processMetadataForStore(boolean inOrder) with inOrder having a value of false. If the configs indicated that we are processing using multiple threads, then an exception will be thrown. 

Rejected Alternatives

If there are alternative ways of accomplishing the same thing, what were they? The purpose of this section is to motivate why the design is the way it is and not some other way.