src/uk/ac/vamsas/client/simpleclient/Lock.java

   1 /*
   2  * This file is part of the Vamsas Client version 0.1.
   3  * Copyright 2009 by Jim Procter, Iain Milne, Pierre Marguerite,
   4  *  Andrew Waterhouse and Dominik Lindner.
   5  *
   6  * Earlier versions have also been incorporated into Jalview version 2.4
   7  * since 2008, and TOPALi version 2 since 2007.
   8  *
   9  * The Vamsas Client is free software: you can redistribute it and/or modify
  10  * it under the terms of the GNU Lesser General Public License as published by
  11  * the Free Software Foundation, either version 3 of the License, or
  12  * (at your option) any later version.
  13  *
  14  * The Vamsas Client is distributed in the hope that it will be useful,
  15  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  16  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  17  * GNU Lesser General Public License for more details.
  18  *
  19  * You should have received a copy of the GNU Lesser General Public License
  20  * along with the Vamsas Client.  If not, see <http://www.gnu.org/licenses/>.
  21  */
  22 package uk.ac.vamsas.client.simpleclient;
  23
  24 import java.io.BufferedInputStream;
  25 import java.io.BufferedOutputStream;
  26 import java.io.File;
  27 import java.io.FileInputStream;
  28 import java.io.FileOutputStream;
  29 import java.io.IOException;
  30 import java.io.OutputStream;
  31 import java.io.RandomAccessFile;
  32 import java.nio.channels.ByteChannel;
  33 import java.nio.channels.FileChannel;
  34 import java.nio.channels.ReadableByteChannel;
  35
  36 import org.apache.commons.logging.LogFactory;
  37
  38 /**
  39  * transient object representing a file lock This lock should hold for all
  40  * processes interacting in a session.
  41  *
  42  * @author jimp
  43  */
  44
  45 public abstract class Lock {
  46   protected org.apache.commons.logging.Log log = LogFactory.getLog(Lock.class);
  47
  48   File target = null; // The file that is being locked
  49
  50   protected RandomAccessFile rafile = null;
  51
  52   /**
  53    * creates a valid Lock (test with <method>isLocked</method>) if a lock could
  54    * be obtained for <param>lockfile</param>
  55    *
  56    * @param lockfile
  57    */
  58   protected Lock(java.io.File lockfile) {
  59     target = lockfile;
  60   }
  61
  62   /**
  63    * test whether the given file is a target or related to the lock on the
  64    * target file.
  65    *
  66    * @param afile
  67    *          a file
  68    * @return true if target is locked and afile is related to target
  69    */
  70   public abstract boolean isTargetLockFile(File afile);
  71
  72   /**
  73    *
  74    * @return true if lock is held on the target
  75    */
  76   public abstract boolean isLocked();
  77
  78   /**
  79    * release lock and close all managed channels to file
  80    *
  81    */
  82   public abstract void release();
  83
  84   /**
  85    * optionally close the open random access channel on the file when releasing
  86    * lock
  87    *
  88    * @param closeChannel
  89    */
  90   public abstract void release(boolean closeChannel);
  91
  92   /**
  93    * gets Locked Stream for reading from
  94    *
  95    * @param atStart
  96    *          true to start reading at beginning of file.
  97    * @return null if file not locked
  98    * @throws IOException
  99    */
 100   public abstract FileInputStream getFileInputStream(boolean atStart)
 101       throws IOException;
 102
 103   /**
 104    * gets Locked stream to write to FileInput always starts at the *end* of the
 105    * file (after any truncation)
 106    *
 107    * @param clear
 108    *          true means file will be cleared to zero length
 109    * @return null if file is not locked
 110    * @throws IOException
 111    */
 112   public abstract FileOutputStream getFileOutputStream(boolean clear)
 113       throws IOException;
 114
 115   /**
 116    * return buffered output stream to locked file.
 117    *
 118    * @param clear
 119    *          - true means file is truncated to 0 length before writing
 120    * @return
 121    */
 122   public abstract BufferedOutputStream getBufferedOutputStream(boolean clear)
 123       throws IOException;
 124
 125   protected void finalize() throws Throwable {
 126     target = null;
 127   }
 128
 129   /**
 130    * return buffered input stream for locked file.
 131    *
 132    * @param atStart
 133    *          - true means read from begining of file
 134    * @return null if file is not locked.
 135    */
 136   public BufferedInputStream getBufferedInputStream(boolean atStart)
 137       throws IOException {
 138     FileInputStream fis = getFileInputStream(atStart);
 139     if (fis != null)
 140       return new BufferedInputStream(fis);
 141     return null;
 142   }
 143
 144   /**
 145    * safe lock target length() function.
 146    *
 147    * @return -1 for non-lockable target, otherwise target's file length
 148    */
 149   public abstract long length();
 150
 151   public abstract RandomAccessFile getRaFile() throws IOException;
 152
 153   public abstract FileChannel getRaChannel() throws IOException;
 154 }