001/*
002 * The contents of this file are subject to the terms of the Common Development and
003 * Distribution License (the License). You may not use this file except in compliance with the
004 * License.
005 *
006 * You can obtain a copy of the License at legal/CDDLv1.0.txt. See the License for the
007 * specific language governing permission and limitations under the License.
008 *
009 * When distributing Covered Software, include this CDDL Header Notice in each file and include
010 * the License file at legal/CDDLv1.0.txt. If applicable, add the following below the CDDL
011 * Header, with the fields enclosed by brackets [] replaced by your own identifying
012 * information: "Portions Copyright [year] [name of copyright owner]".
013 *
014 * Copyright 2008 Sun Microsystems, Inc.
015 * Portions Copyright 2015 ForgeRock AS.
016 */
017
018package org.opends.guitools.controlpanel.util;
019
020/**
021 * This class provides a mechanism for running a task in the background using a
022 * separate thread and providing the caller with notification when it has
023 * completed.
024 * @param <T> type of object returned by this process
025 */
026public abstract class BackgroundTask<T>
027{
028  private BackgroundTaskThread<T> taskThread;
029  private boolean interrupted;
030  /**
031   * Creates a new thread and begins running the task in the background.  When
032   * the task has completed, the {@code backgroundTaskCompleted} method will be
033   * invoked.
034   */
035  public final void startBackgroundTask()
036  {
037    interrupted = false;
038    taskThread = new BackgroundTaskThread<>(this);
039    taskThread.start();
040  }
041
042  /** Interrupts the thread that is running background. */
043  public final void interrupt()
044  {
045    interrupted = true;
046    if (taskThread != null)
047    {
048      taskThread.interrupt();
049    }
050  }
051
052  /**
053   * Returns <CODE>true</CODE> if the thread running in the background is
054   * interrupted and <CODE>false</CODE> otherwise.
055   * @return <CODE>true</CODE> if the thread running in the background is
056   * interrupted and <CODE>false</CODE> otherwise.
057   */
058  public boolean isInterrupted()
059  {
060    return interrupted;
061  }
062
063  /**
064   * Performs all processing associated with the task.
065   *
066   * @return  An {@code Object} with information about the processing performed
067   *          for this task, or {@code null} if no return value is needed.
068   *
069   * @throws Throwable throwable that will be passed through the method
070   *          backgroundTaskCompleted.
071   */
072  public abstract T processBackgroundTask() throws Throwable;
073
074
075
076  /**
077   * This method will be invoked to indicate that the background task has
078   * completed.  If processing completed successfully, then the
079   * {@code Throwable} argument will be {@code null} and the {@code returnValue}
080   * argument will contain the value returned by the
081   * {@code processBackgroundTask} method.  If an exception or error was thrown,
082   * then the {@code throwable} argument will not be {@code null}.
083   *
084   * @param  returnValue  The value returned by the
085   *                      {@code processBackgroundTask} method when processing
086   *                      completed, or {@code null} if no value was returned or
087   *                      an exception was encountered during processing.
088   * @param  throwable    A {@code Throwable} instance (e.g., an exception) that
089   *                      was raised during processing, or {@code null} if all
090   *                      processing completed successfully.
091   */
092  public abstract void backgroundTaskCompleted(T returnValue,
093                                               Throwable throwable);
094}
095