org.simpleframework.util.lease.Lease Maven / Gradle / Ivy

Go to download
/*
 * Lease.java May 2004
 *
 * Copyright (C) 2004, Niall Gallagher 
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation.
 *
 * This library 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 Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General 
 * Public License along with this library; if not, write to the 
 * Free Software Foundation, Inc., 59 Temple Place, Suite 330, 
 * Boston, MA  02111-1307  USA
 */

package org.simpleframework.util.lease;

import java.util.concurrent.TimeUnit;

/**
 * The Lease object is used to keep a keyed resource
 * active. This provides a very simple lease that can be used to
 * track the activity of a resource or system. Keeping track of
 * activity allows resources to be maintained until such time
 * that they are no longer required, allowing the server to clean
 * up any allocated memory, file descriptors, or other such data.
 *
 * @author Niall Gallagher 
 */
public interface Lease {   
   
   /**
    * Determines the duration remaining before the lease expires. 
    * The expiry is given as the number of TimeUnit
    * seconds remaining before the lease expires. If this value is 
    * negative it should be assumed that the lease has expired.
    *
    * @param unit this is the time unit used for the duration
    * 
    * @return the duration remaining within this lease instance
    * 
    * @exception Exception if the expiry could not be acquired     
    */
   public long getExpiry(TimeUnit unit) throws Exception;   
   
   /**
    * This ensures that the leased resource is maintained for the
    * specified number of TimeUnit seconds. Allowing
    * the duration unit to be specified enables the lease system 
    * to maintain a resource with a high degree of accuracy. The
    * accuracy of the leasing system is dependent on how long it
    * takes to clean the resource associated with the lease.
    * 
    * @param duration this is the length of time to renew for
    * @param unit this is the time unit used for the duration
    * 
    * @exception Exception if the lease could not be renewed
    */
   public void renew(long duration, TimeUnit unit) throws Exception;
   
   /**
    * This will cancel the lease and release the resource. This 
    * has the same effect as the renew method with
    * a zero length duration. Once this has been called the
    * Cleaner used should be notified immediately.
    * If the lease has already expired this throws an exception.
    *
    * @exception Exception if the expiry has been passed
    */
   public void cancel() throws Exception;
   
   /**
    * Provides the key for the resource that this lease represents.
    * This can be used to identify the resource should the need
    * arise. Also, this provides a convenient means of identifying
    * leases when using or storing it as an Object.
    *
    * @return this returns the key for the resource represented
    */
   public T getKey();  

}