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
18/**
19 * An observer of <code>Loader</code>.
20 * The users can define a class implementing this
21 * interface and attach an instance of that class to a
22 * <code>Loader</code> object so that it can translate a class file
23 * when the class file is loaded into the JVM.
24 *
25 * @see Loader#addTranslator(ClassPool, Translator)
26 */
27public interface Translator {
28    /**
29     * Is invoked by a <code>Loader</code> for initialization
30     * when the object is attached to the <code>Loader</code> object.
31     * This method can be used for getting (for caching) some
32     * <code>CtClass</code> objects that will be accessed
33     * in <code>onLoad()</code> in <code>Translator</code>.
34     *
35     * @param pool      the <code>ClassPool</code> that this translator
36     *                          should use.
37     * @see Loader
38     * @throws NotFoundException    if a <code>CtClass</code> cannot be found.
39     * @throws CannotCompileException   if the initialization by this method
40     *                                  fails.
41     */
42    void start(ClassPool pool)
43        throws NotFoundException, CannotCompileException;
44
45    /**
46     * Is invoked by a <code>Loader</code> for notifying that
47     * a class is loaded.  The <code>Loader</code> calls
48     *
49     * <ul><pre>
50     * pool.get(classname).toBytecode()</pre></ul>
51     *
52     * to read the class file after <code>onLoad()</code> returns.
53     *
54     * <p><code>classname</code> may be the name of a class
55     * that has not been created yet.
56     * If so, <code>onLoad()</code> must create that class so that
57     * the <code>Loader</code> can read it after <code>onLoad()</code>
58     * returns.
59     *
60     * @param pool      the <code>ClassPool</code> that this translator
61     *                          should use.
62     * @param classname     the name of the class being loaded.
63     * @see Loader
64     * @throws NotFoundException    if a <code>CtClass</code> cannot be found.
65     * @throws CannotCompileException   if the code transformation
66     *                                  by this method fails.
67     */
68    void onLoad(ClassPool pool, String classname)
69        throws NotFoundException, CannotCompileException;
70}
71