/* * Copyright (c) 1998, 2012, Oracle and/or its affiliates. All rights reserved. * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. * * This code is free software; you can redistribute it and/or modify it * under the terms of the GNU General Public License version 2 only, as * published by the Free Software Foundation. Oracle designates this * particular file as subject to the "Classpath" exception as provided * by Oracle in the LICENSE file that accompanied this code. * * This code 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 General Public License * version 2 for more details (a copy is included in the LICENSE file that * accompanied this code). * * You should have received a copy of the GNU General Public License version * 2 along with this work; if not, write to the Free Software Foundation, * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. * * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA * or visit www.oracle.com if you need additional information or have any * questions. */ package com.sun.tools.javadoc; import java.io.File; import java.lang.reflect.InvocationTargetException; import java.lang.reflect.Method; import java.lang.reflect.Modifier; import java.net.URL; import java.net.URLClassLoader; import javax.tools.DocumentationTool; import javax.tools.JavaFileManager; import com.sun.javadoc.*; import com.sun.tools.javac.file.Locations; import com.sun.tools.javac.util.ClientCodeException; import com.sun.tools.javac.util.List; import static com.sun.javadoc.LanguageVersion.*; /** * Class creates, controls and invokes doclets. * *
This is NOT part of any supported API.
* If you write code that depends on this, you do so at your own risk.
* This code and its internal interfaces are subject to change or
* deletion without notice.
*
* @author Neal Gafter (rewrite)
*/
public class DocletInvoker {
private final Class> docletClass;
private final String docletClassName;
private final ClassLoader appClassLoader;
private final Messager messager;
/**
* In API mode, exceptions thrown while calling the doclet are
* propagated using ClientCodeException.
*/
private final boolean apiMode;
private static class DocletInvokeException extends Exception {
private static final long serialVersionUID = 0;
}
private String appendPath(String path1, String path2) {
if (path1 == null || path1.length() == 0) {
return path2 == null ? "." : path2;
} else if (path2 == null || path2.length() == 0) {
return path1;
} else {
return path1 + File.pathSeparator + path2;
}
}
public DocletInvoker(Messager messager, Class> docletClass, boolean apiMode) {
this.messager = messager;
this.docletClass = docletClass;
docletClassName = docletClass.getName();
appClassLoader = null;
this.apiMode = apiMode;
}
public DocletInvoker(Messager messager, JavaFileManager fileManager,
String docletClassName, String docletPath,
ClassLoader docletParentClassLoader,
boolean apiMode) {
this.messager = messager;
this.docletClassName = docletClassName;
this.apiMode = apiMode;
if (fileManager != null && fileManager.hasLocation(DocumentationTool.Location.DOCLET_PATH)) {
appClassLoader = fileManager.getClassLoader(DocumentationTool.Location.DOCLET_PATH);
} else {
// construct class loader
String cpString = null; // make sure env.class.path defaults to dot
// do prepends to get correct ordering
cpString = appendPath(System.getProperty("env.class.path"), cpString);
cpString = appendPath(System.getProperty("java.class.path"), cpString);
cpString = appendPath(docletPath, cpString);
URL[] urls = Locations.pathToURLs(cpString);
if (docletParentClassLoader == null)
appClassLoader = new URLClassLoader(urls, getDelegationClassLoader(docletClassName));
else
appClassLoader = new URLClassLoader(urls, docletParentClassLoader);
}
// attempt to find doclet
Class> dc = null;
try {
dc = appClassLoader.loadClass(docletClassName);
} catch (ClassNotFoundException exc) {
messager.error(Messager.NOPOS, "main.doclet_class_not_found", docletClassName);
messager.exit();
}
docletClass = dc;
}
/*
* Returns the delegation class loader to use when creating
* appClassLoader (used to load the doclet). The context class
* loader is the best choice, but legacy behavior was to use the
* default delegation class loader (aka system class loader).
*
* Here we favor using the context class loader. To ensure
* compatibility with existing apps, we revert to legacy
* behavior if either or both of the following conditions hold:
*
* 1) the doclet is loadable from the system class loader but not
* from the context class loader,
*
* 2) this.getClass() is loadable from the system class loader but not
* from the context class loader.
*/
private ClassLoader getDelegationClassLoader(String docletClassName) {
ClassLoader ctxCL = Thread.currentThread().getContextClassLoader();
ClassLoader sysCL = ClassLoader.getSystemClassLoader();
if (sysCL == null)
return ctxCL;
if (ctxCL == null)
return sysCL;
// Condition 1.
try {
sysCL.loadClass(docletClassName);
try {
ctxCL.loadClass(docletClassName);
} catch (ClassNotFoundException e) {
return sysCL;
}
} catch (ClassNotFoundException e) {
}
// Condition 2.
try {
if (getClass() == sysCL.loadClass(getClass().getName())) {
try {
if (getClass() != ctxCL.loadClass(getClass().getName()))
return sysCL;
} catch (ClassNotFoundException e) {
return sysCL;
}
}
} catch (ClassNotFoundException e) {
}
return ctxCL;
}
/**
* Generate documentation here. Return true on success.
*/
public boolean start(RootDoc root) {
Object retVal;
String methodName = "start";
Class>[] paramTypes = { RootDoc.class };
Object[] params = { root };
try {
retVal = invoke(methodName, null, paramTypes, params);
} catch (DocletInvokeException exc) {
return false;
}
if (retVal instanceof Boolean) {
return ((Boolean)retVal).booleanValue();
} else {
messager.error(Messager.NOPOS, "main.must_return_boolean",
docletClassName, methodName);
return false;
}
}
/**
* Check for doclet added options here. Zero return means
* option not known. Positive value indicates number of
* arguments to option. Negative value means error occurred.
*/
public int optionLength(String option) {
Object retVal;
String methodName = "optionLength";
Class>[] paramTypes = { String.class };
Object[] params = { option };
try {
retVal = invoke(methodName, new Integer(0), paramTypes, params);
} catch (DocletInvokeException exc) {
return -1;
}
if (retVal instanceof Integer) {
return ((Integer)retVal).intValue();
} else {
messager.error(Messager.NOPOS, "main.must_return_int",
docletClassName, methodName);
return -1;
}
}
/**
* Let doclet check that all options are OK. Returning true means
* options are OK. If method does not exist, assume true.
*/
public boolean validOptions(List