/*
   Copyright (C) 2000 - 2007 Grid Systems, S.A.
   
   This program is free software; you can redistribute it and/or modify
   it under the terms of the GNU General Public License, version 2, as
   published by the Free Software Foundation.
   
   This program is distributed in the hope that it will be useful,
   but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  GNU General Public License for more details.
  
  You should have received a copy of the GNU General Public License
  along with this program; if not, write to the Free Software
  Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
  */
  
  package com.gridsystems.innergrid.kernel.genericutils;
  
  import java.lang.reflect.Array;
  import java.util.ArrayList;
  
  import com.gridsystems.exceptions.PagedRequestNoDataException;
  import com.gridsystems.innergrid.kernel.server.KernelContext;
  
  /**
   * Base class for asynchronous paged requests.
   * <p>
   * <b>Subclassing</b>
   * <p>
   * Subclasses must implement the {@link #run()} method, and do it fill the
   * {@link #results} list.
   * <p>
   * The implementation should correctly (and regularly) check for interruption condition,
   * as it is the mechanism used by PagedRequestManager to cancel request executions.
   * <p>
   * <b>Usage</b>
   * <p>
   * A typical iteration loop over a paged request that gets the results, concurrently to
   * the request execution, will have the following layout:
   * <p>
   * <code>
   * PageRequestManager&lt;MyBean&gt; myManager = new PageRequestManager&lt;MyBean&gt;();
   * ...
   * PagedRequest&lt;MyBean&gt; req = myManager.getPagedRequest(id);<br>
   * <br>
   * <b>while</b> (<b>true</b>) {<br>
   * &nbsp; try {<br>
   * &nbsp; &nbsp; MyBean items[] = req.getResults(results.size(), N);<br>
   * &nbsp; &nbsp; <b>if</b> (items == <b>null</b>) <b>break</b>; // No more items<br>
   * &nbsp; &nbsp; <i>// do something whith items</i><br>
   * &nbsp; }<br>
   * &nbsp; <b>catch</b> (PagedRequestTimeoutException e) {<br>
   * &nbsp; &nbsp; <i>// do nothing</i><br>
   * &nbsp; }<br>
   * &nbsp; <b>catch</b> (PagedRequestNoDataException e) {<br>
   * &nbsp; &nbsp; <i>// sleep some time</i><br>
   * &nbsp; }<br>
   * }
   * </code>
   * <p>
   * Or, if we just want to wait until the request execution is finished, and get all its
   * results in one operation, we can do:
   * <p>
   * <code>
   * PagedRequest req = ...;<br>
   * req.join();<br>
   * <br>
   * <b>int</b> count = req.getResultsCount();<br>
   * Object results[] = (count == 0) ? <b>new</b> Object[0] : req.getResults(0, count);
   * </code>
   *
   * @author lgaspart
   * @author rruiz
   * @author Xmas (generics)
   * @version 1.0
   * @param <E> Object type to be paged.
   */
  public abstract class PagedRequest<E extends Object> extends Thread {
    /**
     * Amount of time to sleep between checking if the request has finished.
     */
    private static final long INTERRUPT_SLEEP_DELTA = 1000;
  
    /**
     * Maximum amount of time to sleep when checking if the request has finished.
     */
    private static final long INTERRUPT_SLEEP = 1000;
  
    /**
     * Request sleep time during results retrieval.
     */
    private static final int SLEEP_TIME = 500;
  
    /**
     * Maximum allowed sleep time during results retrieval.
     */
    private static final int MAX_SLEEP_TIME = 60000;
  
   /**
    * Token used for synchronization.
    */
   private static final Object SYNC_TOKEN = new Object();
 
   /**
    * Request counter.
    */
   private static long counter = 0;
 
   /**
    * Request identifier.
    */
   private long id = 0;
 
   /**
    * Request user information.
    */
   protected KernelContext originalContext = null;
 
   /**
    * Request time.
    */
   private long requestTime = 0;
 
   /**
    * The time of the last data access.
    */
   private long lastAccessTime = 0;
 
   /**
    * Must block execution on request.
    */
   private boolean block = false;
 
   /**
    * Results of the request.
    */
   protected ArrayList<E> results = new ArrayList<E>();
 
   /**
    * Class of type E.
    */
   protected final Class<E> theClass;
 
   /**
    * Creates a new instance.
    *
    * @param theClass     Class of type E
    * @param context      The request context
    * @param blockRequest true if the request must be blocking
    */
   public PagedRequest(KernelContext context, Class<E> theClass, boolean blockRequest) {
     super();
     this.setDaemon(true);
 
     synchronized (PagedRequest.SYNC_TOKEN) {
       this.id = PagedRequest.counter++;
     }
     this.theClass = theClass;
     this.requestTime = System.currentTimeMillis();
     this.lastAccessTime = System.currentTimeMillis();
     this.originalContext = (KernelContext)context.clone();
     this.block = blockRequest;
   }
 
   /**
    * Subclasses must implement the request in this method.
    */
   public abstract void run();
 
 
   /**
    * Gets the identifier of the paged request.
    *
    * @return this paged request identifier
    */
   public long getId() {
     return this.id;
   }
 
   /**
    * Gets the user of the paged request.
    *
    * @return the user of this paged request
    */
   public String getUser() {
     return originalContext.getUserName();
   }
 
   /**
    * Gets the hour of the paged request.
    *
    * @return the hour of this paged request
    */
   public long getTime() {
     return requestTime;
   }
 
   /**
    * Gets the number of results of the paged request.
    *
    * @return the number of results in this request
    */
   public int getResultsCount() {
     return (this.results == null) ? 0 : this.results.size();
   }
 
   /**
    * Gets the time of the last access to this request data.
    *
    * @return the last access time
    */
   public long getLastAccessTime() {
     return lastAccessTime;
   }
 
   /**
    * Blocks until the request execution has finished, there are at least from+count
    * results in the pool, the current thread is interrupted or the specified timeout
    * has been reached.
    *
    * @param from    The offset of the first result to get
    * @param count   The number of results to get
    * @param timeout The maximum wait time interval. Use -1 for no timeout
    * @throws PagedRequestNoDataException If the timeout is reached and no results are
    *         available, or the thread is interrupted.
    */
   private void waitForResults(int from, int count, long timeout)
     throws PagedRequestNoDataException {
 
     long ts1 = System.currentTimeMillis();
     this.lastAccessTime = ts1;
 
     int size = from + count;
     while (isAlive() && size > this.results.size()) {
 
       // Controls timeout condition
       if (timeout != -1 && lastAccessTime - ts1 >= timeout) {
         // Only throw timeout if there are no results at all
         if (this.results.size() <= from) {
           throw new PagedRequestNoDataException();
         } else {
           break;
         }
       }
 
       // Waits for more results to be generated
       try {
         sleep(SLEEP_TIME);
       } catch (InterruptedException e) {
         throw new PagedRequestNoDataException();
       }
 
       // Updates last access time, as there is somebody waiting
       this.lastAccessTime = System.currentTimeMillis();
     }
   }
 
   /**
    * Asks for 'count' results, starting at offset 'from'. If not enough data is
    * initially available, it will block during at most 'timeout' milliseconds.
    * <p>
    * The returned value depends on the following rules:
    *
    * <ul>
    *   <li>If, after the timeout interval, there are no available results, but the
    *       request execution is still in progress, a
    *       {@link com.gridsystems.exceptions.PagedRequestNoDataException}
    *       will be thrown.
    *   <li>The same exception will be thrown if the current thread is interrupted.
    *   <li>If, after the timeout interval, there are one or more results,
    *       they will be returned in an array, even if there are less items than
    *       requested.
    *   <li>If the request execution has finished, and there are no results in the
    *       specified range, <code>null</code> will be returned. This marks the
    *       end condition for a retrieval loop.
    * </ul>
    *
    * @param from    The offset of the first result to get
    * @param count   The number of results to get
    * @param timeout The max blocking time
    * @return An array with the obtained results, or null if the request is finished
    *         and 'from' is out of the results bounds.
    * @throws PagedRequestNoDataException In case of timeout
    */
   @SuppressWarnings("unchecked")
   public E[] getResultsTimeout(int from, int count, long timeout)
     throws PagedRequestNoDataException {
     this.lastAccessTime = System.currentTimeMillis();
     int requestedSize = from + count;
 
     // Blocks until enough data available (or timeout)
     waitForResults(from, count, timeout);
 
     // Thread finished, timed out, or results available
     int resultsSize = this.results.size();
 
     if (from >= resultsSize) {
       // We can only be here if the request execution has finished
       return null;
     } else {
       // adjusts item count to the available data
       if (requestedSize > resultsSize) {
         count = resultsSize - from;
       }
 
       // Returns results into an array
       ArrayList<E> array = new ArrayList<E>(count);
       for (int i = 0; i < count; i++) {
         array.add(this.results.get(from + i));
       }
       E[] newArray = (E[])Array.newInstance(theClass, count);
       return array.toArray(newArray);
     }
   }
 
   /**
    * Calls getResultsTimeout() with an appropriate timeout value depending on
    * the 'block' flag specified at construction time.
    *
    * @param from  The initial offset
    * @param count The number of results to retrieve
    * @return An array with the results (either all, or a partial subset), or null
    *         if the request execution has finished and 'from' is out of bounds
    * @throws PagedRequestNoDataException if no results are available yet
    */
   public E[] getResults(int from, int count) throws PagedRequestNoDataException {
     return getResultsTimeout(from, count, block ? MAX_SLEEP_TIME : 0L);
   }
 
   /**
    * Clears the Paged request.
    */
   public void clear() {
     // Interrupt the thread if it is not yet
     if (!this.isInterrupted()) {
       this.interrupt();
     }
 
     // Wait for normal finalization
     long start = System.currentTimeMillis();
     long elapsed = 0;
     while (this.isAlive() && elapsed < INTERRUPT_SLEEP) {
       try {
         Thread.sleep(INTERRUPT_SLEEP_DELTA);
       } catch (InterruptedException e) {
         break;
       }
       elapsed = System.currentTimeMillis() - start;
     }
   }
 }