Package net.sourceforge.jiu.ops

Source Code of net.sourceforge.jiu.ops.Operation

/*
* Operation
*
* Copyright (c) 2000, 2001, 2002, 2003, 2004, 2005, 2006 Marco Schmidt
* All rights reserved.
*/

package net.sourceforge.jiu.ops;

import java.util.Vector;
import net.sourceforge.jiu.ops.MissingParameterException;
import net.sourceforge.jiu.ops.OperationFailedException;
import net.sourceforge.jiu.ops.ProgressListener;
import net.sourceforge.jiu.ops.WrongParameterException;

/**
* <p>
* Base class for all operations.
* </p>
* <p>
* It supports progress notification.
* All classes that want to be notified by a new progress level of the operation
* (defined as value between 0.0f (nothing has been done so far) to 1.0f
* (operation finished)) must implement the {@link ProgressListener} interface.
* </p>
* <p>
* An abortion state is stored in each Operation object.
* It should be queried by a running operation from time to time
* (via {@link #getAbort()} - if it returns <code>true</code>,
* the operation should terminate and return control to the caller.
* The abort state can be modified using {@link #setAbort(boolean)}.
* </p>
* @author Marco Schmidt
*/
public abstract class Operation
{
/* <p>
* This class class contains a generic system to add parameters to an operation.
* Whether an item becomes a parameter is often unclear and must be decided by
* the operation implementor.
* As an example: one could create an image rotation class with a numerical parameter
* for the degrees of rotation.
* One could also define a class of its own for each 90, 180 and 270 degrees
* (excluding other values).
* </p>
* <p>
* The generic parameter system is insufficient in some situations.
* Example: A parameter can be defined to be of class Integer or Long, but it cannot
* be forced to be in a certain interval.
* Even if such a case could be solved by a specially-designed class, checking
* of parameters (and maybe their relations among each other) can be done by
* overriding the {@link #checkParams()} method.
* </p>
*/
  private boolean abort;
  private Vector progressListeners;

  /**
   * This constructor creates two internal empty lists for progress listeners and parameters.
   */
  public Operation()
  {
    abort = false;
    progressListeners = new Vector();
  }

  /**
   * Adds the argument progress listener to the internal list of
   * progress listeners.
   * Does not check if the argument already exists in that list, so you have
   * to check for duplicates yourself.
   *
   * @param progressListener the progress listener to be added
   */
  public void addProgressListener(ProgressListener progressListener)
  {
    if (progressListener == null)
    {
      return;
    }
    if (!progressListeners.contains(progressListener))
    {
      progressListeners.addElement(progressListener);
    }
  }

  /**
   * Adds several progress listeners to this operation object.
   * @param progressListeners contains zero or more objects implementing ProgressListener;
   *  each will be added by calling {@link #addProgressListener} on it
   */
  public void addProgressListeners(Vector progressListeners)
  {
    if (progressListeners != null)
    {
      int index = 0;
      while (index < progressListeners.size())
      {
        ProgressListener listener = (ProgressListener)progressListeners.elementAt(index++);
        addProgressListener(listener);
      }
    }
  }

  /**
   * Returns the current abort status.
   * If <code>true</code>, a running operation should terminate what it is doing
   * (return from {@link #process()}).
   * @return abort status
   * @see #setAbort
   */
  public boolean getAbort()
  {
    return abort;
  }

  /**
   * This method does the actual work of the operation.
   * It must be called after all parameters have been given to the operation object.
   * @throws WrongParameterException if at least one of the input parameters was
   *  not initialized appropriately (values out of the valid interval, etc.)
   * @throws MissingParameterException if any mandatory parameter was not given to the operation
   * @throws OperationFailedException
   */
  public void process() throws
    MissingParameterException,
    OperationFailedException,
    WrongParameterException
  {
  }

  /**
   * Removes the argument progress listener from the internal list of
   * progress listeners.
   * @param progressListener the progress listener to be removed
   */
  public void removeProgressListener(ProgressListener progressListener)
  {
    progressListeners.removeElement(progressListener);
  }

  /**
   * Sets a new abort status.
   * @param newAbortStatus the new status
   * @see #getAbort
   */
  public void setAbort(boolean newAbortStatus)
  {
    abort = newAbortStatus;
  }

  /**
   * This method will notify all registered progress listeners
   * about a new progress level.
   * The argument must be from 0.0f to 1.0f where 0.0f marks the
   * beginning and 1.0f completion.
   * The progress value should not be smaller than any value that
   * was previously set.
   * @param progress new progress value, from 0.0 to 1.0
   */
  public void setProgress(float progress)
  {
    if (progress < 0.0f || progress > 1.0f)
    {
      throw new IllegalArgumentException("Progress values must be from" +
        " 0.0f to 1.0f; got " + progress);
    }
    int index = 0;
    while (index < progressListeners.size())
    {
      ProgressListener pl =
        (ProgressListener)progressListeners.elementAt(index++);
      if (pl != null)
      {
        pl.setProgress(progress);
      }
    }
  }

  /**
   * This method will notify all registered progress listeners
   * about a new progress level.
   * Simply checks the arguments and calls <code>setProgress((float)zeroBasedIndex / (float)totalItems);</code>.
   * @param zeroBasedIndex the index of the item that was just processed, zero-based
   * @param totalItems the number of items that will be processed
   */
  public void setProgress(int zeroBasedIndex, int totalItems)
  {
    if (zeroBasedIndex < 0 || zeroBasedIndex >= totalItems ||
        totalItems < 1)
    {
      throw new IllegalArgumentException("No valid arguments " +
        " zeroBasedIndex=" + zeroBasedIndex + ", totalItems=" +
        totalItems);
    }
    setProgress((float)zeroBasedIndex / (float)totalItems);
  }
}
TOP

Related Classes of net.sourceforge.jiu.ops.Operation

TOP
Copyright © 2018 www.massapi.com. All rights reserved.
All source code are property of their respective owners. Java is a trademark of Sun Microsystems, Inc and owned by ORACLE Inc. Contact coftware#gmail.com.