Service
Date: 2017-07-08

com.google.protobuf

## Interface Service

-     public interface Service

  Abstract base interface for protocol-buffer-based RPC services. Services themselves are abstract classes (implemented either by servers or as stubs), but they subclass this base interface. The methods of this interface can be used to call the methods of the service without knowing its exact type at compile time (analogous to the Message interface).

  Starting with version 2.3.0, RPC implementations should not try to build on this, but should instead provide code generator plugins which generate code specific to the particular RPC implementation. This way the generated code can be more appropriate for the implementation in use and can avoid unnecessary layers of indirection.

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `callMethod(Descriptors.MethodDescriptor method, RpcController controller, Message request, RpcCallback<Message> done)` Call a method of the service specified by MethodDescriptor.
    `Descriptors.ServiceDescriptor` | `getDescriptorForType()` Get the `ServiceDescriptor` describing this service and its methods.
    `Message` | `getRequestPrototype(Descriptors.MethodDescriptor method)` `callMethod()` requires that the request passed in is of a particular subclass of `Message`.
    `Message` | `getResponsePrototype(Descriptors.MethodDescriptor method)` Like `getRequestPrototype()`, but gets a prototype of the response message.

- - ### Method Detail

    - #### getDescriptorForType

          Descriptors.ServiceDescriptor getDescriptorForType()

      Get the `ServiceDescriptor` describing this service and its methods.

    - #### callMethod

          void callMethod(Descriptors.MethodDescriptor method,
                        RpcController controller,
                        Message request,
                        RpcCallback<Message> done)

      Call a method of the service specified by MethodDescriptor. This is normally implemented as a simple `switch()` that calls the standard definitions of the service's methods.

      Preconditions:

      - `method.getService() == getDescriptorForType()`
      - `request` is of the exact same class as the object returned by `getRequestPrototype(method)`.
      - `controller` is of the correct type for the RPC implementation being used by this Service. For stubs, the "correct type" depends on the RpcChannel which the stub is using. Server-side Service implementations are expected to accept whatever type of `RpcController` the server-side RPC implementation uses.

      Postconditions:

      - `done` will be called when the method is complete. This may be before `callMethod()` returns or it may be at some point in the future.
      - The parameter to `done` is the response. It must be of the exact same type as would be returned by `getResponsePrototype(method)`.
      - If the RPC failed, the parameter to `done` will be `null`. Further details about the failure can be found by querying `controller`.

    - #### getRequestPrototype

          Message getRequestPrototype(Descriptors.MethodDescriptor method)

      `callMethod()` requires that the request passed in is of a particular subclass of `Message`. `getRequestPrototype()` gets the default instances of this type for a given method. You can then call `Message.newBuilderForType()` on this instance to construct a builder to build an object which you can then pass to `callMethod()`.

      Example:

             MethodDescriptor method =
               service.getDescriptorForType().findMethodByName("Foo");
             Message request =
               stub.getRequestPrototype(method).newBuilderForType()
                   .mergeFrom(input).build();
             service.callMethod(method, request, callback);

    - #### getResponsePrototype

          Message getResponsePrototype(Descriptors.MethodDescriptor method)

      Like `getRequestPrototype()`, but gets a prototype of the response message. `getResponsePrototype()` is generally not needed because the `Service` implementation constructs the response message itself, but it may be useful in some cases to know ahead of time what type of object will be returned.