/*
 *  Licensed to the Apache Software Foundation (ASF) under one or more
 *  contributor license agreements.  See the NOTICE file distributed with
 *  this work for additional information regarding copyright ownership.
 *  The ASF licenses this file to You 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 org.apache.coyote;

import org.apache.tomcat.util.net.SocketEvent;

Adapter. This represents the entry point in a coyote-based servlet container.
Author:
Remy Maucherat
See Also:
ProtocolHandler/**
 * Adapter. This represents the entry point in a coyote-based servlet container.
 *
 *
 * @author Remy Maucherat
 * @see ProtocolHandler
 */
public interface Adapter {

    
Call the service method, and notify all listeners
Params:
req – The request object
res – The response object
Throws:
Exception – if an error happens during handling of
  the request. Common errors are:
  
IOException if an input/output error occurs and we are
  processing an included servlet (otherwise it is swallowed and
  handled by the top level error handler mechanism)
      
ServletException if a servlet throws an exception and
 we are processing an included servlet (otherwise it is swallowed
 and handled by the top level error handler mechanism)
 
 Tomcat should be able to handle and log any other exception ( including
 runtime exceptions )/**
     * Call the service method, and notify all listeners
     *
     * @param req The request object
     * @param res The response object
     *
     * @exception Exception if an error happens during handling of
     *   the request. Common errors are:
     *   <ul><li>IOException if an input/output error occurs and we are
     *   processing an included servlet (otherwise it is swallowed and
     *   handled by the top level error handler mechanism)
     *       <li>ServletException if a servlet throws an exception and
     *  we are processing an included servlet (otherwise it is swallowed
     *  and handled by the top level error handler mechanism)
     *  </ul>
     *  Tomcat should be able to handle and log any other exception ( including
     *  runtime exceptions )
     */
    public void service(Request req, Response res) throws Exception;

    
Prepare the given request/response for processing. This method requires
that the request object has been populated with the information available
from the HTTP headers.
Params:
req – The request object
res – The response object
Throws:
Exception – If the processing fails unexpectedly
Returns:
true if processing can continue, otherwise
        false in which case an appropriate error will have
        been set on the response/**
     * Prepare the given request/response for processing. This method requires
     * that the request object has been populated with the information available
     * from the HTTP headers.
     *
     * @param req The request object
     * @param res The response object
     *
     * @return <code>true</code> if processing can continue, otherwise
     *         <code>false</code> in which case an appropriate error will have
     *         been set on the response
     *
     * @throws Exception If the processing fails unexpectedly
     */
    public boolean prepare(Request req, Response res) throws Exception;

    public boolean asyncDispatch(Request req,Response res, SocketEvent status)
            throws Exception;

    public void log(Request req, Response res, long time);

    
Assert that request and response have been recycled. If they have not
then log a warning and force a recycle. This method is called as a safety
check when a processor is being recycled and may be returned to a pool
for reuse.
Params:
req – 
           Request
res – 
           Response/**
     * Assert that request and response have been recycled. If they have not
     * then log a warning and force a recycle. This method is called as a safety
     * check when a processor is being recycled and may be returned to a pool
     * for reuse.
     *
     * @param req
     *            Request
     * @param res
     *            Response
     */
    public void checkRecycled(Request req, Response res);

    
Provide the name of the domain to use to register MBeans for components
associated with the connector.
Returns:
 The MBean domain name/**
     * Provide the name of the domain to use to register MBeans for components
     * associated with the connector.
     *
     * @return  The MBean domain name
     */
    public String getDomain();
}