Cacheable.java #1

package com.perforce.api;

import java.io.*;
import java.util.*;

/*
 * Copyright (c) 2001, Perforce Software, All rights reserved.
 *
 * Permission is hereby granted, free of charge, to any person obtaining a
 * copy of this software and associated documentation files (the
 * "Software"), to deal in the Software without restriction, including
 * without limitation the rights to use, copy, modify, merge, publish,
 * distribute, sublicense, and/or sell copies of the Software, and to
 * permit persons to whom the Software is furnished to do so, subject to
 * the following conditions:
 *
 * The above copyright notice and this permission notice shall be included
 * in all copies or substantial portions of the Software.
 *
 * THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
 * OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
 * IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
 * CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
 * TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
 * SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 */

/**
 * An interface that indicates the implementing class can be cached for some
 * period of time. Implementing classes will be stored in a
 * <code>HashDecay</code> instance. Each instantiating class must create its
 * own <code>HashDecay</code> instance and return a reference to it through 
 * the <code>getCache</code> method.
 *
 * The update time is what is used by the <code>HasDecay</code> to determine
 * when an object will decay and be discarded.
 *
 * @see HashDecay
 * @author <a href="mailto:david@markley.cc">David Markley</a>
 * @version $Date: 2003/12/02 $ $Revision: #1 $
 */
public interface Cacheable {

  /** Returns the time, in milliseconds, for this object's last update. */
  public long getUpdateTime();

  /** Sets the update time for this object to the current time. */
  public void refreshUpdateTime();

  /** Returns the time, in milliseconds, that this object was synchronized. */
  public long getSyncTime();

  /**
   * Tests this object to see if it is out of sync. Checks to see if the
   * expiration time is within the specified number of milliseconds.
   *
   * @param threshold Number of milliseconds.
   * @return True if the object will be out of sync within the threshold.
   */
  public boolean outOfSync(long threshold);

  /** Invalidates this object. */  
  public void invalidate();
  
  /** Marks this object as being in in sync or valid. */
  public void inSync();

  /** Removes any cached objects. */
  public void clearCache();

  /** Returns the HashDecay instance for this class */
  public HashDecay getCache();
  
  /**
   * Stores this object back into Perforce, creating it if it
   * didn't already exist.
   */
  public void commit() throws CommitException;

  /**
   * Brings this object back into sync with Perforce. This also sets the
   * sets the update and sync time for this object.
   */
  public void sync() throws PerforceException;
}