/*
 * Copyright 2014 The gRPC Authors
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package io.grpc;

import javax.annotation.concurrent.ThreadSafe;

/**
 * Interface to initiate processing of incoming remote calls. Advanced applications and generated
 * code will implement this interface to allows {@link Server}s to invoke service methods.
 */
@ThreadSafe
public interface ServerCallHandler<RequestT, ResponseT> {
  /**
   * Produce a non-{@code null} listener for the incoming call. Implementations are free to call
   * methods on {@code call} before this method has returned.
   *
   * <p>Since {@link Metadata} is not thread-safe, the caller must not access (read or write) {@code
   * headers} after this point.
   *
   * <p>If the implementation throws an exception, {@code call} will be closed with an error.
   * Implementations must not throw an exception if they started processing that may use {@code
   * call} on another thread.
   *
   * @param call object for responding to the remote client.
   * @return listener for processing incoming request messages for {@code call}
   */
  ServerCall.Listener<RequestT> startCall(
      ServerCall<RequestT, ResponseT> call,
      Metadata headers);
}

@@ -942,334 +942,807 @@
   * 
-Produce a non-%7B@code null%7D listener for the incoming call. Implementations are free to call%0A   * methods on %7B@code call%7D before this method has returned.%0A   *%0A   * %3Cp%3ESince %7B@link Metadata%7D is not thread-safe, the caller must not access (read or write) %7B@code%0A   * headers%7D after this point.%0A   *%0A   * %3Cp%3EIf the implementation
+Starts asynchronous processing of an incoming call.%0A   *%0A   * %3Cp%3ECallers of this method transfer their ownership of the non-thread-safe %7B@link ServerCall%7D%0A   * and %7B@link Metadata%7D arguments to the %7B@link ServerCallHandler%7D implementation for processing.%0A   * Ownership means that the implementation may invoke methods on %7B@code call%7D and %7B@code headers%7D%0A   * while %7B@link #startCall%7D runs and at any time after it returns normally. On the other hand, if%0A   * %7B@link #startCall%7D throws, ownership of %7B@code call%7D and %7B@code headers%7D reverts to the caller%0A   * and the implementation loses the right to call methods on these objects (from some other%0A   * thread, say).%0A   *%0A   * %3Cp%3EOwnership also includes the responsibility to eventually close %7B@code call%7D. In particular,%0A   * if %7B@link #startCall%7D
  thr
@@ -1763,86 +1763,223 @@
 on, 
-%7B@cod
+th
 e call
-%7D will be
+er must handle it by
  clos
-ed with an error.%0A   * Implementations must not
+ing %7B@code call%7D%0A   * with an error. Since %7B@code call%7D can only be closed once, an implementation can report errors%0A   * either to %7B@link ServerCall#close%7D for itself or by
  throw
+ing
  an 
@@ -1991,84 +1991,198 @@
 tion
- if they started processing that may use
+, but not both.%0A   *%0A   * %3Cp%3EReturns a non-%7B@code null%7D listener for the incoming call. Callers of this method must%0A   * arrange for events associated with
  %7B@code
-%0A   *
  call%7D 
-on another
+to be delivered
  th
+e
 re
-ad
 .%0A  
@@ -2245,16 +2245,114 @@
 client.%0A
+   * @param headers request headers received from the client but open to modification by an owner%0A
    * @re

Clarify the ServerCallHandler API contract. (#8339)