[refactor][java] Improve docs and code quality about KeyValueSchema usages

[BewareMyPower]

Motivation

First, it's hard to know the default encoding type of a KeyValue schema
from the API and its JavaDocs, see

pulsar/pulsar-client-api/src/main/java/org/apache/pulsar/client/api/Schema.java

Lines 386 to 391 in fd94897

	/**
	* Key Value Schema using passed in key and value schemas.
	*/
	static <K, V> Schema<KeyValue<K, V>> KeyValue(Schema<K> key, Schema<V> value) {
	return DefaultImplementation.getDefaultImplementation().newKeyValueSchema(key, value);
	}

The default encoding type could only be found in KeyValueSchemaImpl#of
method from another module (pulsar-client).

Second, there are much raw use of parameterized class, including
KeyValueSchema and KeyValue from pulsar-common module. This use
harms the code quality because it could lose the type safety.

Modifications

For the 1st issue, call another overload of Schema#KeyValue method and
note the default encoding type so that it's clear that the encoding
type of Schema#KeyValue(Schema<K>, Schema<V>) method is INLINE.

For the 2nd issue, leverage Java's type inference feature to make sure
the type arguments of KeyValue are the same as the type arguments of
KeyValueSchema in a TypedMessageBuilderImpl instane.
getKeyValueSchema method is added to simplify the code.

Verifying this change

• Make sure that the change passes the CI checks.

This change is already covered by existing tests, such as SchemaTest and
NullValueTest in pulsar-broker module.

Documentation

Check the box below or label this PR directly.

Need to update docs?

• doc-required
  (Your PR needs to update docs and you will update later)

• doc-not-needed
  (Please explain why)

• doc
  (Your PR contains doc changes)

• doc-complete
  (Docs have been already added)

[github-actions]

@BewareMyPower Please provide a correct documentation label for your PR.
Instructions see Pulsar Documentation Label Guide.

[BewareMyPower]

@Demogorgon314 @codelipenghui @eolivelli @lhotari @gaoran10 Could you take a look?

[asafm]

While you're here, can you explain why when the schema is KeyValue, and the encoding is SEPARATED, it is forbidden to use this method to se the key of the message?

[BewareMyPower]

Because when the encoding is SEPARATED, the partition key should be set by a KeyValue object.

Producer<KeyValue<String, String>> producer = client.newProducer(
                Schema.KeyValue(Schema.STRING, Schema.STRING, KeyValueEncodingType.SEPARATED))
        .topic("my-topic")
        .create();
producer.newMessage().value(new KeyValue<>("key", "value")).send()

With the SEPARATED key value encoding type, the code above will send a message whose partition key is "key" and value is "value". If it's allowed to set the partition key here, conflicts will happen.

There is no design of the key value schema, I just guessed the reason why key and keyBytes methods are forbidden and followed the previous behavior in this PR

[asafm]

I don't understand why.
Why can't we do

.newMessage() // this creates a builder
.key(theKey)
.value(theValue)
.send()

[BewareMyPower]

Because the schema type is Schema<KeyValue<K, V>>, the value's type must be KeyValue<K, V>, then the code will look like:

.key("key")
.value(new KeyValue<>("key-1", "value"))

The root cause is that Pulsar only stores the schema of the value. So it can only support key schema by passing a pair of "key" and "value" as the whole value.

[github-actions]

The pr had no activity for 30 days, mark with Stale label.