1/*
2 * Javassist, a Java-bytecode translator toolkit.
3 * Copyright (C) 1999-2007 Shigeru Chiba. All Rights Reserved.
4 *
5 * The contents of this file are subject to the Mozilla Public License Version
6 * 1.1 (the "License"); you may not use this file except in compliance with
7 * the License.  Alternatively, the contents of this file may be used under
8 * the terms of the GNU Lesser General Public License Version 2.1 or later.
9 *
10 * Software distributed under the License is distributed on an "AS IS" basis,
11 * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
12 * for the specific language governing rights and limitations under the
13 * License.
14 */
15
16package javassist;
17
18import java.io.InputStream;
19import java.net.URL;
20
21/**
22 * <code>ClassPath</code> is an interface implemented by objects
23 * representing a class search path.
24 * <code>ClassPool</code> uses those objects for reading class files.
25 *
26 * <p>The users can define a class implementing this interface so that
27 * a class file is obtained from a non-standard source.
28 *
29 * @see ClassPool#insertClassPath(ClassPath)
30 * @see ClassPool#appendClassPath(ClassPath)
31 * @see ClassPool#removeClassPath(ClassPath)
32 */
33public interface ClassPath {
34    /**
35     * Opens a class file.
36     * This method may be called just to examine whether the class file
37     * exists as well as to read the contents of the file.
38     *
39     * <p>This method can return null if the specified class file is not
40     * found.  If null is returned, the next search path is examined.
41     * However, if an error happens, this method must throw an exception
42     * so that the search will be terminated.
43     *
44     * <p>This method should not modify the contents of the class file.
45     *
46     * @param classname         a fully-qualified class name
47     * @return          the input stream for reading a class file
48     * @see javassist.Translator
49     */
50    InputStream openClassfile(String classname) throws NotFoundException;
51
52    /**
53     * Returns the uniform resource locator (URL) of the class file
54     * with the specified name.
55     *
56     * @param classname         a fully-qualified class name.
57     * @return null if the specified class file could not be found.
58     */
59    URL find(String classname);
60
61    /**
62     * This method is invoked when the <code>ClassPath</code> object is
63     * detached from the search path.  It will be an empty method in most of
64     * classes.
65     */
66    void close();
67}
68