Mercurial > jdk8-mips64-public > langtools / file revision

 /*

  * 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.

  *

  *  <p><b>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.</b>

  *

  * @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<String[]> optlist) {

         Object retVal;

         String options[][] = optlist.toArray(new String[optlist.length()][]);

         String methodName = "validOptions";

         DocErrorReporter reporter = messager;

         Class<?>[] paramTypes = { String[][].class, DocErrorReporter.class };

         Object[] params = { options, reporter };

         try {

             retVal = invoke(methodName, Boolean.TRUE, 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;

         }

     }

     /**

      * Return the language version supported by this doclet.

      * If the method does not exist in the doclet, assume version 1.1.

      */

     public LanguageVersion languageVersion() {

         try {

             Object retVal;

             String methodName = "languageVersion";

             Class<?>[] paramTypes = new Class<?>[0];

             Object[] params = new Object[0];

             try {

                 retVal = invoke(methodName, JAVA_1_1, paramTypes, params);

             } catch (DocletInvokeException exc) {

                 return JAVA_1_1;

             }

             if (retVal instanceof LanguageVersion) {

                 return (LanguageVersion)retVal;

             } else {

                 messager.error(Messager.NOPOS, "main.must_return_languageversion",

                                docletClassName, methodName);

                 return JAVA_1_1;

             }

         } catch (NoClassDefFoundError ex) { // for boostrapping, no Enum class.

             return null;

         }

     }

     /**

      * Utility method for calling doclet functionality

      */

     private Object invoke(String methodName, Object returnValueIfNonExistent,

                           Class<?>[] paramTypes, Object[] params)

         throws DocletInvokeException {

             Method meth;

             try {

                 meth = docletClass.getMethod(methodName, paramTypes);

             } catch (NoSuchMethodException exc) {

                 if (returnValueIfNonExistent == null) {

                     messager.error(Messager.NOPOS, "main.doclet_method_not_found",

                                    docletClassName, methodName);

                     throw new DocletInvokeException();

                 } else {

                     return returnValueIfNonExistent;

                 }

             } catch (SecurityException exc) {

                 messager.error(Messager.NOPOS, "main.doclet_method_not_accessible",

                                docletClassName, methodName);

                 throw new DocletInvokeException();

             }

             if (!Modifier.isStatic(meth.getModifiers())) {

                 messager.error(Messager.NOPOS, "main.doclet_method_must_be_static",

                                docletClassName, methodName);

                 throw new DocletInvokeException();

             }

             ClassLoader savedCCL =

                 Thread.currentThread().getContextClassLoader();

             try {

                 if (appClassLoader != null) // will be null if doclet class provided via API

                     Thread.currentThread().setContextClassLoader(appClassLoader);

                 return meth.invoke(null , params);

             } catch (IllegalArgumentException exc) {

                 messager.error(Messager.NOPOS, "main.internal_error_exception_thrown",

                                docletClassName, methodName, exc.toString());

                 throw new DocletInvokeException();

             } catch (IllegalAccessException exc) {

                 messager.error(Messager.NOPOS, "main.doclet_method_not_accessible",

                                docletClassName, methodName);

                 throw new DocletInvokeException();

             } catch (NullPointerException exc) {

                 messager.error(Messager.NOPOS, "main.internal_error_exception_thrown",

                                docletClassName, methodName, exc.toString());

                 throw new DocletInvokeException();

             } catch (InvocationTargetException exc) {

                 Throwable err = exc.getTargetException();

                 if (apiMode)

                     throw new ClientCodeException(err);

                 if (err instanceof java.lang.OutOfMemoryError) {

                     messager.error(Messager.NOPOS, "main.out.of.memory");

                 } else {

                     messager.error(Messager.NOPOS, "main.exception_thrown",

                                docletClassName, methodName, exc.toString());

                     exc.getTargetException().printStackTrace();

                 }

                 throw new DocletInvokeException();

             } finally {

                 Thread.currentThread().setContextClassLoader(savedCCL);

             }

     }

 }