/*
 * FindBugs - Find Bugs in Java programs
 * Copyright (C) 2006, University of Maryland
 *
 * 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; either
 * version 2.1 of the License, or (at your option) any later version.
 *
 * 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 edu.umd.cs.findbugs.classfile;

Interface for a basic code base in which we can look up resources but not
necessarily scan for the list of all resources.
Author:
David Hovemeyer/**
 * Interface for a basic code base in which we can look up resources but not
 * necessarily scan for the list of all resources.
 *
 * @author David Hovemeyer
 */
public interface ICodeBase {

    enum Discovered {

        
Codebase was explicitly specified. /** Codebase was explicitly specified. */
        SPECIFIED,

        
Codebase was discovered as a nested archive in another codebase. /** Codebase was discovered as a nested archive in another codebase. */
        NESTED,

        
Codebase was referenced in the Class-Path attribute of a Jar manifest
of another codebase.
/**
         * Codebase was referenced in the Class-Path attribute of a Jar manifest
         * of another codebase.
         */
        IN_JAR_MANIFEST,

        
Codebase was discovered in the system classpath. /** Codebase was discovered in the system classpath. */
        IN_SYSTEM_CLASSPATH,
    }
    
Get the codebase locator describing the location of this codebase.
Returns:
the ICodeBaseLocator/**
     * Get the codebase locator describing the location of this codebase.
     *
     * @return the ICodeBaseLocator
     */
    public ICodeBaseLocator getCodeBaseLocator();

    
Look up a resource in this code base.
Params:
resourceName – 
           name of the resource to look up
Returns:
ICodeBaseEntry representing the resource or null if the resource
        cannot be found in this code base/**
     * Look up a resource in this code base.
     *
     * @param resourceName
     *            name of the resource to look up
     * @return ICodeBaseEntry representing the resource or null if the resource
     *         cannot be found in this code base
     */
    public ICodeBaseEntry lookupResource(String resourceName);

    
Designate this code base as an application codebase.
Params:
isAppCodeBase – 
           true if this is an application codebase, false if not/**
     * Designate this code base as an application codebase.
     *
     * @param isAppCodeBase
     *            true if this is an application codebase, false if not
     */
    public void setApplicationCodeBase(boolean isAppCodeBase);

    
Return whether or not this codebase is an application codebase.
Returns:
true if this is an application codebase, false if not/**
     * Return whether or not this codebase is an application codebase.
     *
     * @return true if this is an application codebase, false if not
     */
    public boolean isApplicationCodeBase();

    
Set how this codebase was discovered.
Params:
howDiscovered – 
           one of the constants SPECIFIED, NESTED, IN_JAR_MANIFEST, or
           IN_SYSTEM_CLASSPATH/**
     * Set how this codebase was discovered.
     *
     * @param howDiscovered
     *            one of the constants SPECIFIED, NESTED, IN_JAR_MANIFEST, or
     *            IN_SYSTEM_CLASSPATH
     */
    public void setHowDiscovered(ICodeBase.Discovered howDiscovered);

    
Return how this codebase was discovered.
Returns:
one of the constants SPECIFIED, NESTED, IN_JAR_MANIFEST, or
        IN_SYSTEM_CLASSPATH/**
     * Return how this codebase was discovered.
     *
     * @return one of the constants SPECIFIED, NESTED, IN_JAR_MANIFEST, or
     *         IN_SYSTEM_CLASSPATH
     */
    public ICodeBase.Discovered getHowDiscovered();

    
Return whether or not this code base contains any source files.
Returns:
true if the code base contains source file(s), false if it does
        not contain source files/**
     * Return whether or not this code base contains any source files.
     *
     * @return true if the code base contains source file(s), false if it does
     *         not contain source files
     */
    public boolean containsSourceFiles() throws InterruptedException;

    
Get the filesystem pathname of this codebase.
Returns:
the filesystem pathname of this codebase, or null if this
        codebase is not accessible via the filesystem/**
     * Get the filesystem pathname of this codebase.
     *
     * @return the filesystem pathname of this codebase, or null if this
     *         codebase is not accessible via the filesystem
     */
    public String getPathName();

    
Set timestamp indicating the most recent time when any of the files in
the codebase were modified.
Params:
lastModifiedTime – 
           timestamp when any codebase files were most-recently modified/**
     * Set timestamp indicating the most recent time when any of the files in
     * the codebase were modified.
     *
     * @param lastModifiedTime
     *            timestamp when any codebase files were most-recently modified
     */
    public void setLastModifiedTime(long lastModifiedTime);

    
Get timestamp indicating the most recent time when any of the files in
the codebase were modified. This information is only likely to be
accurate if an ICodeBaseIterator has been used to scan the resources in
the codebase (scannable codebases only, obviously).
Returns:
timestamp when any codebase files were most-recently modified, -1
        if unknown/**
     * Get timestamp indicating the most recent time when any of the files in
     * the codebase were modified. This information is only likely to be
     * accurate if an ICodeBaseIterator has been used to scan the resources in
     * the codebase (scannable codebases only, obviously).
     *
     * @return timestamp when any codebase files were most-recently modified, -1
     *         if unknown
     */
    public long getLastModifiedTime();

    
This method should be called when done using the code base.
/**
     * This method should be called when done using the code base.
     */
    public void close();
}