/*
 * 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.axis2.jaxws.core.controller;

import org.apache.axis2.jaxws.core.InvocationContext;

import javax.xml.ws.AsyncHandler;
import javax.xml.ws.Response;
import java.util.concurrent.Future;

/**
 * The <tt>InvocationController</tt> is an interface modeling the invocation of a
 * target web service.  All of the information that the InvocationController needs 
 * should exist within the InvocatonContext that is passed in to the various invoke 
 * methods.
 * <p/>
 * The request information is passed in within the InvocationContext.  The InvocationController
 * assumes that there is a MessageContext within that InvocationContext that is populated with all
 * of the information that it needs to invoke.  If not, an error will be returned.  Once the
 * response comes back, the information for that response will be held inside of the MessageContext
 * representing the response, that exists in the InvocationContext.
 * <p/>
 * The InvocationController supports four different invocation patterns:
 * <p/>
 * 1) synchronous - This is represented by the {@link #invoke(InvocationContext)} method.  This is a
 * blocking, request/response call to the web service.
 * <p/>
 * 2) one-way - This is represented by the {@link #invokeOneWay(InvocationContext)} method.  This is
 * a one-way invocation that only returns errors related to sending the message.  If an error occurs
 * while processing, the client will not be notified.
 * <p/>
 * 3) asynchronous (callback) - {@link #invokeAsync(InvocationContext, AsyncHandler)}
 * <p/>
 * 4) asynchronous (polling) - {@link #invokeAsync(InvocationContext)}
 */
public interface InvocationController {

    /**
     * Performs a synchronous (blocking) invocation of a target service.  The InvocationContext
     * passed in should contain a valid MessageContext containing the properties and message to be
     * sent for the request.  The response contents will be processed and placed in the
     * InvocationContext as well.
     *
     * @param ic
     * @return
     */
    public InvocationContext invoke(InvocationContext ic);

    /**
     * Performs a one-way invocation of the client.  This is SHOULD NOT be a robust invocation, so
     * any fault that occurs during the processing of the request will not be returned to the
     * client.  Errors returned to the client are problems that occurred during the sending of the
     * message to the server.
     *
     * @param ic
     */
    public void invokeOneWay(InvocationContext ic) throws Exception;

    /**
     * Performs an asynchronous (non-blocking) invocation of the client based on a callback model.
     * The AsyncHandler that is passed in is the callback that the client programmer supplied when
     * they invoked their JAX-WS Dispatch or their SEI-based dynamic proxy.
     *
     * @param ic
     * @param callback
     * @return
     */
    public Response invokeAsync(InvocationContext ic);

    /**
     * Performs an asynchronous (non-blocking) invocation of the client based on a polling model.
     * The Response object that is returned allows the client programmer to poll against it to see
     * if a response has been sent back by the server.
     *
     * @param ic
     * @return
     */
    public Future<?> invokeAsync(InvocationContext ic, AsyncHandler asyncHandler);

}