package com.limegroup.gnutella.library;

import java.io.File;
import java.util.Iterator;
import java.util.List;
import java.util.concurrent.locks.Lock;

import org.limewire.listener.ListenerSupport;

import com.limegroup.gnutella.URN;

/** A read-only view of a collection of files. */
public interface FileView extends Iterable<FileDesc>, ListenerSupport<FileViewChangeEvent> {
        
    /** Gets the current name of this collection. */
    String getName();
    
    /** Returns the size of all files within this view, in <b>bytes</b>. */
    long getNumBytes();
    
    /**
     * Returns a list of all the file descriptors in this list that exist in the
     * given directory, in any order.
     * 
     * This method is not recursive; files in any of the directory's children
     * are not returned.
     * 
     * This operation is <b>not</b> efficient, and should not be done often.
     */
    List<FileDesc> getFilesInDirectory(File directory);
   
    /**
     * Returns the <tt>FileDesc</tt> for the specified URN. This only returns
     * one <tt>FileDesc</tt>, even though multiple indices are possible.
     * 
     * @param urn the urn for the file
     * @return the <tt>FileDesc</tt> corresponding to the requested urn, or
     *         <tt>null</tt> if no matching <tt>FileDesc</tt> could be found
     */
    FileDesc getFileDesc(URN urn);        

    /**
     * Returns the <tt>FileDesc</tt> that is wrapping this <tt>File</tt> or
     * null if the file is not shared or not a store file.
     */
    FileDesc getFileDesc(File f);

    /**
     * Returns all FileDescs that match this URN.
     */
    List<FileDesc> getFileDescsMatching(URN urn);

    /**
     * Returns the FileDesc at the given index. This returns the FileDesc for
     * which FileDesc.getIndex == index. This is supported as an optimization so
     * that classes can efficiently locate matches.
     */
    FileDesc getFileDescForIndex(int index);

    /** Returns true if this list contains a FileDesc for the given file. */
    boolean contains(File file);

    /**
     * Return true if this list contains this FileDesc, false otherwise.
     */
    boolean contains(FileDesc fileDesc);

    /**
     * Returns an iterator over all FileDescs. The returned iterator is *NOT*
     * thread safe. You must lock on FileList while acquiring and using it.
     */
    Iterator<FileDesc> iterator();

    /**
     * Returns an iterable that is thread-safe and can be used over a period of
     * time (iterating through it piecemeal, with time lapses). The returned
     * iterable is much slower and more inefficient than the default iterator,
     * though, so only use it if absolutely necessary.
     */
    Iterable<FileDesc> pausableIterable();

    /**
     * Returns the number of files in this list.
     */
    int size();

    /** Returns a lock to use when iterating over this FileList. */
    Lock getReadLock();
    
}