Document StubFactory (Fixes #381)

Author: ST-DDT

docs/en/client/configuration.md

@@ -11,6 +11,7 @@ This section describes how you can configure your grpc-spring-boot-starter clien
 - [Configuration via Beans](#configuration-via-beans)
   - [GrpcChannelConfigurer](#grpcchannelconfigurer)
   - [ClientInterceptor](#clientinterceptor)
+  - [StubFactory](#stubfactory)
   - [StubTransformer](#stubtransformer)
 
 ## Additional Topics <!-- omit in toc -->
@@ -132,6 +133,45 @@ There are three ways to add a `ClientInterceptor` to your channel.
 - Explicitly list them in the `@GrpcClient#interceptors` or `@GrpcClient#interceptorNames` field
 - Use a `StubTransformer` and call `stub.withInterceptors(ClientInterceptor... interceptors)`
 
+### StubFactory
+
+A `StubFactory` is used to create a `Stub` of a specific type. The registered stub factories will be checked in order
+and the first applicable factory will be used to create the stub.
+
+This library has build in support for the `Stub` types defined in grpc-java:
+
+- [`AsyncStubs`](https://grpc.github.io/grpc-java/javadoc/io/grpc/stub/AbstractAsyncStub.html)
+- [`BlockingStubs`](https://grpc.github.io/grpc-java/javadoc/io/grpc/stub/AbstractBlockingStub.html)
+- [`FutureStubs`](https://grpc.github.io/grpc-java/javadoc/io/grpc/stub/AbstractFutureStub.html)
+
+But you can easily add support for other `Stub` types by adding a custom `StubFactory` to your application context.
+
+````java
+@Component
+public class MyCustomStubFactory implements StubFactory {
+
+    @Override
+    public MyCustomStub<?> createStub(Class<? extends AbstractStub<?>> stubType, Channel channel) {
+        try {
+            Class<?> enclosingClass = stubType.getEnclosingClass();
+            Method factoryMethod = enclosingClass.getMethod("newMyBetterFutureStub", Channel.class);
+            return stubType.cast(factoryMethod.invoke(null, channel));
+        } catch (Exception e) {
+            throw new BeanInstantiationException(stubType, "Failed to create gRPC stub", e);
+        }
+    }
+
+    @Override
+    public boolean isApplicable(Class<? extends AbstractStub<?>> stubType) {
+        return AbstractMyCustomStub.class.isAssignableFrom(stubType);
+    }
+
+}
+````
+
+> **Note:** Please report missing stub types (and the corresponding library) in our issue tracker so that we can add
+> support if possible.
+
 ### StubTransformer
 
 The stub transformer allows you to modify `Stub`s right before they are injected to your beans.

docs/en/client/getting-started.md

@@ -126,6 +126,9 @@ This section assumes that you have already defined and generated your [Protobuf
   automatically attach it to all `Stub`s (**NOT** `Channel`s). The
   [`CallCredentialsHelper`](https://javadoc.io/page/net.devh/grpc-client-spring-boot-autoconfigure/latest/net/devh/boot/grpc/client/security/CallCredentialsHelper.html)
   utility class helps you to create commonly used `CallCredentials` types and related `StubTransformer`.
+- [`StubFactory`](https://javadoc.io/page/net.devh/grpc-client-spring-boot-autoconfigure/latest/net/devh/boot/grpc/client/stubfactory/StubFactory.html):
+  A factory that can be used to create a specfic `Stub` type from a `Channel`. Multiple `StubFactory`s can be registered to support different stub types.
+  See also [Configuration -> StubFactory](configuration.md#stubfactory).
 - [`StubTransformer`](https://javadoc.io/page/net.devh/grpc-client-spring-boot-autoconfigure/latest/net/devh/boot/grpc/client/inject/StubTransformer.html):
   A transformer that will be applied to all client `Stub`s before they are injected.
   See also [Configuration -> StubTransformer](configuration.md#stubtransformer).