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

Go to download
/*
 * Controller.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 org.simpleframework.util.lease.LeaseException;

/**
 * The Controller forms the interface to the lease
 * management system. There are two actions permitted for leased
 * resources, these are lease issue and lease renewal. When the
 * lease is first issued it is scheduled for the initial contract
 * duration. Once issued the lease can be renewed with another
 * duration, which can be less than the previous duration used.
 *
 * @author Niall Gallagher
 *
 * @see org.simpleframework.util.lease.Maintainer
 */
interface Controller {
   
   /**
    * This method will establish a contract for the given duration.
    * If the contract duration expires before it is renewed then a
    * notification is sent, typically to a Cleaner to
    * to signify that the resource should be released. The contract
    * can also be cancelled by providing a zero length duration.
    * 
    * @param contract a contract representing a leased resource
    *
    * @exception Exception if the lease could not be done
    */   
   public void issue(Contract contract) throws Exception;
   
   /**
    * This ensures that the contract is renewed for the duration on
    * the contract, which may have changed since it was issued or
    * last renewed. If the duration on the contract has changed this
    * will insure the previous contract duration is revoked and the 
    * new duration is used to maintain the leased resource.
    *
    * @param contract a contract representing a leased resource
    *
    * @exception Exception if the lease could not be done
    */
   public void renew(Contract contract) 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.
    *
    * @param contract a contract representing a leased resource
    *
    * @exception Exception if the expiry has been passed
    */
   public void cancel(Contract contract) throws Exception;
   
   /**
    * This method is used to cancel all outstanding leases and to
    * close the controller. Closing the controller ensures that it
    * can no longer be used to issue or renew leases. All resources
    * occupied by the controller are released, including threads,
    * memory, and all leased resources occupied by the instance.   
    * 
    * @throws LeaseException if the controller can not be closed
    */
   public void close() ;
}