/*
 * Copyright 2006 The Apache Software Foundation.
 *
 * 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 org.apache.axis2.util;

import org.apache.axis2.AxisFault;
import org.apache.axis2.context.MessageContext;

/**
 * This is the interface for a piece of code that will plug into the user
 * programming model impl (e.g. JAX-WS impl) and will be invoked while on the
 * ultimate thread of execution.  It is intended to provide a mechanism to
 * allow information to be migrated between the Axis2 contexts and thread
 * local storage.
 * 
 * Note: It is up to each particular programming model impl to decide whether
 * or not they wish to make use of the ThreadContextMigrators.
 * 
 * For each general MEP, here is the invocation pattern:
 * 
 * [one-way inbound]
 * migrateContextToThread(req)
 * cleanupThread(req)
 * 
 * [req/rsp inbound]
 * migrateContextToThread(req)
 * migrateThreadToContext(rsp)
 * cleanupContext(rsp)
 * cleanupThread(req)
 * 
 * [one-way outbound]
 * migrateThreadToContext(req)
 * cleanupContext(req)
 * 
 * [req/rsp outbound (both sync and async)]
 * migrateThreadToContext(req)
 * cleanupContext(req)
 * migrateContextToThread(rsp)
 * Note: there is no corresponding cleanupThread(rsp); one of the inbound
 *       cases would need to handle this
 * 
 * If a fault occurs during execution of one of the migrators, it will be
 * treated like any other service fault (i.e. like what will happen if we can't
 * deliver the message to a service or if a handler fails.
 * 
 * The cleanup* methods can be expected to be invoked after any exeception
 * that occurs within the scope of the migration that would cause that scope
 * to be left so that the thread and/or context may be cleaned up properly. 
 */
public interface ThreadContextMigrator
{
  /**
   * This method will be invoked when the processing of the message is
   * guaranteed to be on the thread of execution that will be used in
   * user space.  It will be invoked for incoming messages.
   * Implementations of this interface can use the information found in the
   * MessageContext to determine whether a request or response is being
   * processed.
   * (e.g. MessageContext.getAxisOperation().getMessageExchangePattern())
   * 
   * @param messageContext
   * @throws AxisFault
   */
  void migrateContextToThread(MessageContext messageContext) throws AxisFault;

  /**
   * This method will be invoked when the processing of the message is
   * guaranteed to still be on the thread of execution that was used in user
   * space, after all processing has completed (i.e. when the particular
   * processing of a message is unwinding.)  It provides a mechanism which can
   * be used to clean up the TLS.
   *   
   * @param messageContext
   */
  void cleanupThread(MessageContext messageContext);

  /**
   * This method will be invoked when the processing of the message is
   * guaranteed to still be on the thread of execution that was used in
   * user space.  It will be invoked for both outgoing messages.
   * Implementations of this interface can use the information found in the
   * MessageContext to determine whether a request or response is being
   * processed.
   * (e.g. MessageContext.getAxisOperation().getMessageExchangePattern())
   * 
   * @param messageContext
   * @throws AxisFault
   */
  void migrateThreadToContext(MessageContext messageContext) throws AxisFault;
  
  /**
   * This method will be invoked when the processing of the message is
   * guaranteed to be on the thread of execution that will be used in user
   * space, after all processing has completed (i.e. when the particular
   * processing of a message is unwinding.)  It provides a mechanism which can
   * be used to clean up the MessageContext or restore TLS.
   *   
   * @param messageContext
   */
  void cleanupContext(MessageContext messageContext);
}