AsynchronousFileWriter.java

/*
 * Copyright (c) 2007 BUSINESS OBJECTS SOFTWARE LIMITED
 * All rights reserved.
 * 
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 * 
 *     * Redistributions of source code must retain the above copyright notice,
 *       this list of conditions and the following disclaimer.
 *  
 *     * Redistributions in binary form must reproduce the above copyright
 *       notice, this list of conditions and the following disclaimer in the
 *       documentation and/or other materials provided with the distribution.
 *  
 *     * Neither the name of Business Objects nor the names of its contributors
 *       may be used to endorse or promote products derived from this software
 *       without specific prior written permission.
 *  
 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
 * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
 * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
 * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
 * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
 * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
 * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
 * POSSIBILITY OF SUCH DAMAGE.
 */


/*
 * AsynchronousFileWriter.java
 * Creation date: Jan 17, 2006.
 * By: Edward Lam
 */
package org.openquark.cal.machine;

import java.io.ByteArrayInputStream;
import java.io.InputStream;

import org.openquark.cal.compiler.CompilerMessageLogger;



/**
 * Interface to allow the files generated by the compiler to be serialized to the program resource repository on a separate thread. 
 * 
 * Starts automatically when adding a file to write.
 * 
 * @author Edward Lam
 */
public abstract class AsynchronousFileWriter {
    
    /**
     * The in-memory version of a file.
     * @author Bo Ilic
     */
    public static final class FileData {
        
        private final ProgramResourceLocator.File fileLocator;
        
        /** entire contents of the file */
        private final byte[] bytes;
        
        public FileData(ProgramResourceLocator.File fileLocator, byte[] bytes) {
            if (fileLocator == null || bytes == null) {
                throw new NullPointerException();
            }
            this.fileLocator = fileLocator;
            this.bytes = new byte[bytes.length];
            System.arraycopy(bytes, 0, this.bytes, 0, this.bytes.length);
        }
        
        /**
         * @return the data as an input stream
         */
        public InputStream getInputStream() {
            return new ByteArrayInputStream(bytes);
        }
        
        /**         
         * @return size of the FileData in bytes.
         */
        public int getSize() {
            return bytes.length;
        }

        /**
         * @return the locator for the file whose data will be written.
         */
        public ProgramResourceLocator.File getFileLocator() {
            return this.fileLocator;
        }             
    }

    /**
     * The compilation thread must call this method after it finishes with all calls to addFileToWrite.     
     */
    public abstract void stopAcceptingFiles();
    
    /**
     * The compilation thread calls this method to add a file to write. This will return (almost) immediately if
     * the AsynchronousFileWriter is not "full." Otherwise, this method will write the files on the calling thread 
     * until the pending number of bytes has been reduced and then notify the asynchronous saving thread.
     * 
     * The file writer thread will be started the first time this is called.
     * 
     * @param fileData cannot be null.
     * @param logger the logger to use for logging error messages.
     */
    public abstract void addFileToWrite(AsynchronousFileWriter.FileData fileData, CompilerMessageLogger logger);
       
    /**
     * Wait for the file writer to meet the following conditions:
     * - stopAcceptingFiles() has been called
     * - all files have been written
     * @param logger the logger to use for logging error messages.
     * @throws InterruptedException if the caller is interrupted while waiting.
     */
    public abstract void waitForFilesToBeWritten(CompilerMessageLogger logger) throws InterruptedException;

}