/*
 * CDDL HEADER START
 *
 * The contents of this file are subject to the terms of the
 * Common Development and Distribution License (the "License").
 * You may not use this file except in compliance with the License.
 *
 * You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE
 * or http://www.opensolaris.org/os/licensing.
 * See the License for the specific language governing permissions
 * and limitations under the License.
 *
 * When distributing Covered Code, include this CDDL HEADER in each
 * file and include the License file at usr/src/OPENSOLARIS.LICENSE.
 * If applicable, add the following below this CDDL HEADER, with the
 * fields enclosed by brackets "[]" replaced with your own identifying
 * information: Portions Copyright [yyyy] [name of copyright owner]
 *
 * CDDL HEADER END
 */

/*
 * Copyright (c) 2010, 2012, Oracle and/or its affiliates. All rights reserved.
 */

package com.oracle.solaris.vp.panel.common.action;

import java.awt.event.ActionEvent;
import java.util.concurrent.*;
import javax.swing.*;
import com.oracle.solaris.vp.util.misc.*;

/**
 * The {@code StructuredAction} encapsulates an action that {@link #work
 * produces} an output ({@code O}) based optionally on {@link #getPresetInput
 * preset} ({@code P}) and {@link #getRuntimeInput runtime} ({@code I}) input.
 * <p/>
 * Invocation flow is as follows:
 * <p/>
 * <table>
 *   <tr><td align='center' colspan='3'>{@link #actionPerformed}</td></tr>
 *   <tr><td align='center' colspan='3'>&darr;</td></tr>
 *   <tr><td align='center' colspan='3'>{@link #asyncInvoke}</td></tr>
 *   <tr><td align='center' colspan='3'>&darr;</td></tr>
 *   <tr>
 *     <td align='center' colspan='3'>{@link #invoke(Object) invoke(I)}</td>
 *   </tr>
 *   <tr><td align='center' colspan='3'>&darr;</td></tr>
 *   <tr valign='top'>
 *     <td>
 *	 <table>
 *	   <tr><td align='center'>&darr;&uarr;</td></tr>
 *	   <tr><td align='center'>{@link #getPresetInput}</td></tr>
 *	 </table>
 *     </td>
 *     <td>
 *	 <table>
 *	   <tr><td align='center'>&darr;&uarr;</td></tr>
 *	   <tr><td align='center'>{@link #getRuntimeInput}</td></tr>
 *	 </table>
 *     </td>
 *     <td>
 *	 <table>
 *	   <tr><td align='center'>&darr;</td></tr>
 *	   <tr><td align='center'>{@link #work}</td></tr>
 *	 </table>
 *     </td>
 *   </tr>
 * </table>
 * <p/>
 * See the summaries of each to for a description of the features that each
 * method provides.
 * <p/>
 * A typical subclass will implement {@link #work}, and optionally {@link
 * #getRuntimeInput} if it needs to create or retrieve run-time data (like user
 * input) prior to running.
 * <p/>
 * Simpler implementations that don't require runtime input may override {@link
 * #invoke(Object) invoke(I)} instead.
 */
public class StructuredAction<P, I, O> extends AbstractAction {
    //
    // Instance data
    //

    private boolean loops;
    private P pInput;

    // Use a thread pool to invoke actions outside of the AWT event thread, and
    // to autmatically handle uncaught exceptions and queued requests
    protected final ThreadPoolExecutor threadPool;
    {
	String name = TextUtil.getBaseName(getClass()) + "-";
	ThreadFactory factory = new NamedThreadFactory(name);

	// Unbounded
	BlockingQueue<Runnable> queue = new LinkedBlockingQueue<Runnable>();

	// Use a thread pool with a single core thread to automatically handle
	// uncaught exceptions and queued requests.  Use a minuscule timeout so
	// that threads herein don't hold up shutdown of the JVM.
	threadPool = new ThreadPoolExecutor(
	    1, 1, 1, TimeUnit.NANOSECONDS, queue, factory);

	threadPool.allowCoreThreadTimeOut(true);
    }

    //
    // Constructors
    //

    /**
     * Constructs a {@code StructuredAction} with the given name and initial
     * preset input.
     */
    public StructuredAction(String text, P pInput) {
	putValue(Action.NAME, text);
	setPresetInput(pInput);
    }

    /**
     * Constructs a {@code StructuredAction} with the given name {@code null}
     * preset input.
     */
    public StructuredAction(String text) {
	this(text, null);
    }

    //
    // Action methods
    //

    /**
     * Calls {@link #asyncInvoke}.
     */
    @Override
    public void actionPerformed(ActionEvent e) {
	asyncInvoke();
    }

    //
    // StructuredAction methods
    //

    /**
     * Runs the given {@code Runnable} in this {@code
     * StructuredAction}'s thread pool.
     *
     * @param	    r
     *		    the {@code Runnable} to run
     */
    public void asyncExec(Runnable r) {
	threadPool.execute(r);
    }

    /**
     * Schedules a call to {@link #invoke(Object) invoke(I)} in this
     * {@code StructuredAction}'s thread pool, ignoring any resulting
     * {@link ActionAbortedException} or {@link ActionFailedException}.
     */
    public void asyncInvoke() {
	asyncInvoke(null);
    }

    protected void asyncInvoke(final I rtInput) {
	asyncExec(
	    new Runnable() {
		@Override
		public void run() {
		    try {
			invoke(rtInput);
		    } catch (ActionAbortedException ignore) {
		    } catch (ActionFailedException ignore) {
		    }
		}
	    });
    }

    /**
     * Gets whether this action loops repeatedly until cancelled or successful.
     * See {@link #invoke(Object) invoke(I)}.
     * <p\>
     * The default value is {@code false}.
     */
    public boolean getLoops() {
	return loops;
    }

    /**
     * Gets the preset input for this action.
     */
    public P getPresetInput() {
	return pInput;
    }

    /**
     * Retrieves any runtime data needed to perform this action.  In most cases
     * this input will come from the user.  This object is passed to {@link
     * #work} and its ilk.
     * <p\>
     * This default implementation does nothing and returns {@code null}.
     *
     * @param	    pInput
     *		    the preset input, set prior to the invocation of this action
     *
     * @param	    rtInput
     *		    the result from any previous invocations of this method
     *		    (from the context of a single invocation of {@link
     *		    #invoke}), or {@code null} if this method has not been
     *		    called yet
     *
     * @exception   ActionAbortedException
     *		    if this action is cancelled, presumably by the user
     */
    public I getRuntimeInput(P pInput, I rtInput)
	throws ActionAbortedException {

	return null;
    }

    /**
     * Calls {@link #invoke(Object) invoke(null)}.
     */
    public O invoke() throws ActionAbortedException, ActionFailedException {
	return invoke(null);
    }

    /**
     * Invokes this {@link StructuredAction} with the given initial input.  The
     * behavior of this method when this {@link StructuredAction} is not enabled
     * may be undefined.
     * <p/>
     * This implementation retrieves input from {@link #getRuntimeInput}, then
     * passes it on to {@link #work}.
     * <p/>
     * If the latter throws an {@link ActionFailedException} and {@link
     * #getLoops} returns:
     * <ul>
     *	 <li>
     *	   {@code true}: this process is repeated until cancelled via (an
     *	   {@link ActionAbortedException}) or successful
     *	 </li>
     *	 <li>
     *	   {@code false}: the {@link ActionFailedException} is rethrown
     *	 </li>
     * </ul>
     *
     * @param	    rtInput
     *		    an initial runtime input
     *
     * @return	    the value returned by {@link #work}
     *
     * @exception   ActionAbortedException
     *		    thrown by {@link #getRuntimeInput} or {@link #work}
     *
     * @exception   ActionFailedException
     *		    thrown by {@link #work}
     */
    protected O invoke(I rtInput)
	throws ActionAbortedException, ActionFailedException {

	P pInput = this.pInput;

	while (true) {
	    rtInput = getRuntimeInput(pInput, rtInput);

	    try {
		return work(pInput, rtInput);
	    } catch (ActionFailedException e) {
		if (!getLoops()) {
		    throw e;
		}
	    }
	}
    }

    /**
     * Updates this action's properties based on the preset input or other
     * criteria.  This default implementation does nothing.
     */
    public void refresh() {
    }

    /**
     * Sets whether this action loops repeatedly until cancelled or successful.
     * See {@link #invoke(Object) invoke(I)}.
     * <p\>
     * The default value is {@code false}.
     */
    protected void setLoops(boolean loops) {
	this.loops = loops;
    }

    /**
     * Sets the preset input for this action.  This value is passed by {@code
     * #invoke(Object) invoke(I)} to {@link #getRuntimeInput} and {@link #work}.
     */
    public void setPresetInput(P pInput) {
	this.pInput = pInput;
	refresh();
    }

    /**
     * Does the core work of this action.
     * <p\>
     * This default implementation does nothing and returns {@code null}.
     *
     * @param	    pInput
     *		    the preset input, set prior to the invocation of this action
     *
     * @param	    rtInput
     *		    data retrieved from {@link #getRuntimeInput}
     *
     * @return	    the output of this action, if any
     *
     * @exception   ActionAbortedException
     *		    if the action is cancelled
     *
     * @exception   ActionFailedException
     *		    if an error occurs
     */
    public O work(P pInput, I rtInput) throws ActionAbortedException,
	ActionFailedException {

	return null;
    }
}