/*
 * 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
 */
public interface ICodeBase {
	/** Codebase was explicitly specified. */
	public static final int SPECIFIED = 0;

	/** Codebase was discovered as a nested archive in another codebase. */
	public static final int NESTED = 1;

	/** Codebase was referenced in the Class-Path attribute of a Jar manifest of another codebase. */
	public static final int IN_JAR_MANIFEST = 2;

	/** Codebase was discovered in the system classpath. */
	public static final int IN_SYSTEM_CLASSPATH = 3;

	/**
	 * Get the codebase locator describing the location of this codebase.
	 *
	 * @return the ICodeBaseLocator
	 */
	public ICodeBaseLocator getCodeBaseLocator();

	/**
	 * 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.
	 *
	 * @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.
	 *
	 * @return true if this is an application codebase, false if not
	 */
	public boolean isApplicationCodeBase();

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

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

	/**
	 * 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.
	 *
	 * @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.
	 *
	 * @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).
	 *
	 * @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.
	 */
	public void close();
}