AnnotationParser

//
//  ========================================================================
//  Copyright (c) 1995-2014 Mort Bay Consulting Pty. Ltd.
//  ------------------------------------------------------------------------
//  All rights reserved. This program and the accompanying materials
//  are made available under the terms of the Eclipse Public License v1.0
//  and Apache License v2.0 which accompanies this distribution.
//
//      The Eclipse Public License is available at
//      http://www.eclipse.org/legal/epl-v10.html
//
//      The Apache License v2.0 is available at
//      http://www.opensource.org/licenses/apache2.0.php
//
//  You may elect to redistribute this code under either of these licenses.
//  ========================================================================
//

package org.eclipse.jetty.annotations;

import java.io.File;
import java.io.IOException;
import java.io.InputStream;
import java.net.URI;
import java.net.URL;
import java.net.URLClassLoader;
import java.util.Arrays;
import java.util.List;
import java.util.Locale;
import java.util.Set;
import java.util.jar.JarEntry;
import java.util.jar.JarInputStream;

import org.eclipse.jetty.util.ConcurrentHashSet;
import org.eclipse.jetty.util.Loader;
import org.eclipse.jetty.util.MultiException;
import org.eclipse.jetty.util.log.Log;
import org.eclipse.jetty.util.log.Logger;
import org.eclipse.jetty.util.resource.Resource;
import org.eclipse.jetty.webapp.JarScanner;
import org.objectweb.asm.AnnotationVisitor;
import org.objectweb.asm.ClassReader;
import org.objectweb.asm.ClassVisitor;
import org.objectweb.asm.FieldVisitor;
import org.objectweb.asm.MethodVisitor;
import org.objectweb.asm.Opcodes;


/**
 * AnnotationParser
 *
 * Use asm to scan classes for annotations. A SAX-style parsing is done.
 * Handlers are registered which will be called back when various types of
 * entity are encountered, eg a class, a method, a field.
 *
 * Handlers are not called back in any particular order and are assumed
 * to be order-independent.
 *
 * As a registered Handler will be called back for each annotation discovered
 * on a class, a method, a field, the Handler should test to see if the annotation
 * is one that it is interested in.
 *
 * For the servlet spec, we are only interested in annotations on classes, methods and fields,
 * so the callbacks for handling finding a class, a method a field are themselves
 * not fully implemented.
 */
public class AnnotationParser
{
    private static final Logger LOG = Log.getLogger(AnnotationParser.class);

    protected Set<String> _parsedClassNames = new ConcurrentHashSet<String>();

    protected static int ASM_OPCODE_VERSION = Opcodes.ASM5; //compatibility of api


    /**
     * Convert internal name to simple name
     *
     * @param name
     * @return
     */
    public static String normalize (String name)
    {
        if (name==null)
            return null;

        if (name.startsWith("L") && name.endsWith(";"))
            name = name.substring(1, name.length()-1);

        if (name.endsWith(".class"))
            name = name.substring(0, name.length()-".class".length());

        return name.replace('/', '.');
    }

    /**
     * Convert internal names to simple names.
     *
     * @param list
     * @return
     */
    public static String[] normalize (String[] list)
    {
        if (list == null)
            return null;
        String[] normalList = new String[list.length];
        int i=0;
        for (String s : list)
            normalList[i++] = normalize(s);
        return normalList;
    }


    /**
     * ClassInfo
     *
     * Immutable information gathered by parsing class header.
     *
     */
    public class ClassInfo
    {
        final Resource _containingResource;
        final String _className;
        final int _version;
        final int _access;
        final String _signature;
        final String _superName;
        final String[] _interfaces;

        public ClassInfo(Resource resource, String className, int version, int access, String signature, String superName, String[] interfaces)
        {
            super();
            _containingResource = resource;
            _className = className;
            _version = version;
            _access = access;
            _signature = signature;
            _superName = superName;
            _interfaces = interfaces;
        }

        public String getClassName()
        {
            return _className;
        }

        public int getVersion()
        {
            return _version;
        }

        public int getAccess()
        {
            return _access;
        }

        public String getSignature()
        {
            return _signature;
        }

        public String getSuperName()
        {
            return _superName;
        }

        public String[] getInterfaces()
        {
            return _interfaces;
        }

        public Resource getContainingResource()
        {
            return _containingResource;
        }
    }


    /**
     * MethodInfo
     *
     * Immutable information gathered by parsing a method on a class.
     */
    public class MethodInfo
    {
        final ClassInfo _classInfo;
        final String _methodName;
        final int _access;
        final String _desc;
        final String _signature;
        final String[] _exceptions;

        public MethodInfo(ClassInfo classInfo, String methodName, int access, String desc, String signature, String[] exceptions)
        {
            super();
            _classInfo = classInfo;
            _methodName = methodName;
            _access = access;
            _desc = desc;
            _signature = signature;
            _exceptions = exceptions;
        }

        public ClassInfo getClassInfo()
        {
            return _classInfo;
        }

        public String getMethodName()
        {
            return _methodName;
        }

        public int getAccess()
        {
            return _access;
        }

        public String getDesc()
        {
            return _desc;
        }

        public String getSignature()
        {
            return _signature;
        }

        public String[] getExceptions()
        {
            return _exceptions;
        }
    }


    /**
     * FieldInfo
     *
     * Immutable information gathered by parsing a field on a class.
     *
     */
    public class FieldInfo
    {
        final ClassInfo _classInfo;
        final String _fieldName;
        final int _access;
        final String _fieldType;
        final String _signature;
        final Object _value;

        public FieldInfo(ClassInfo classInfo, String fieldName, int access, String fieldType, String signature, Object value)
        {
            super();
            _classInfo = classInfo;
            _fieldName = fieldName;
            _access = access;
            _fieldType = fieldType;
            _signature = signature;
            _value = value;
        }

        public ClassInfo getClassInfo()
        {
            return _classInfo;
        }

        public String getFieldName()
        {
            return _fieldName;
        }

        public int getAccess()
        {
            return _access;
        }

        public String getFieldType()
        {
            return _fieldType;
        }

        public String getSignature()
        {
            return _signature;
        }

        public Object getValue()
        {
            return _value;
        }
    }


    /**
     * Handler
     *
     * Signature for all handlers that respond to parsing class files.
     */
    public static interface Handler
    {
        public void handle(ClassInfo classInfo);
        public void handle(MethodInfo methodInfo);
        public void handle (FieldInfo fieldInfo);
        public void handle (ClassInfo info, String annotationName);
        public void handle (MethodInfo info, String annotationName);
        public void handle (FieldInfo info, String annotationName);
    }


    /**
     * AbstractHandler
     *
     * Convenience base class to provide no-ops for all Handler methods.
     *
     */
    public static abstract class AbstractHandler implements Handler
    {

        @Override
        public void handle(ClassInfo classInfo)
        {
           //no-op
        }

        @Override
        public void handle(MethodInfo methodInfo)
        {
            // no-op
        }

        @Override
        public void handle(FieldInfo fieldInfo)
        {
            // no-op
        }

        @Override
        public void handle(ClassInfo info, String annotationName)
        {
            // no-op
        }

        @Override
        public void handle(MethodInfo info, String annotationName)
        {
            // no-op
        }

        @Override
        public void handle(FieldInfo info, String annotationName)
        {
           // no-op
        }
    }


    /**
     * MyMethodVisitor
     *
     * ASM Visitor for parsing a method. We are only interested in the annotations on methods.
     */
    public class MyMethodVisitor extends MethodVisitor
    {
        final MethodInfo _mi;
        final Set<? extends Handler> _handlers;

        public MyMethodVisitor(final Set<? extends Handler> handlers,
                               final ClassInfo classInfo,
                               final int access,
                               final String name,
                               final String methodDesc,
                               final String signature,
                               final String[] exceptions)
        {
            super(ASM_OPCODE_VERSION);
            _handlers = handlers;
            _mi = new MethodInfo(classInfo, name, access, methodDesc,signature, exceptions);
        }


        /**
         * We are only interested in finding the annotations on methods.
         *
         * @see org.objectweb.asm.MethodVisitor#visitAnnotation(java.lang.String, boolean)
         */
        @Override
        public AnnotationVisitor visitAnnotation(String desc, boolean visible)
        {
            String annotationName = normalize(desc);
            for (Handler h:_handlers)
                h.handle(_mi, annotationName);
            return null;
        }
    }


    /**
     * MyFieldVisitor
     *
     * An ASM visitor for parsing Fields.
     * We are only interested in visiting annotations on Fields.
     *
     */
    public class MyFieldVisitor extends FieldVisitor
    {
        final FieldInfo _fieldInfo;
        final Set<? extends Handler> _handlers;


        public MyFieldVisitor(final Set<? extends Handler> handlers,
                              final ClassInfo classInfo,
                              final int access,
                              final String fieldName,
                              final String fieldType,
                              final String signature,
                              final Object value)
        {
            super(ASM_OPCODE_VERSION);
            _handlers = handlers;
            _fieldInfo = new FieldInfo(classInfo, fieldName, access, fieldType, signature, value);
        }


        /**
         * Parse an annotation found on a Field.
         *
         * @see org.objectweb.asm.FieldVisitor#visitAnnotation(java.lang.String, boolean)
         */
        @Override
        public AnnotationVisitor visitAnnotation(String desc, boolean visible)
        {
            String annotationName = normalize(desc);
            for (Handler h : _handlers)
               h.handle(_fieldInfo, annotationName);

            return null;
        }
    }


    /**
     * MyClassVisitor
     *
     * ASM visitor for a class.
     */
    public class MyClassVisitor extends ClassVisitor
    {

        final Resource _containingResource;
        final Set<? extends Handler> _handlers;
        ClassInfo _ci;

        public MyClassVisitor(Set<? extends Handler> handlers, Resource containingResource)
        {
            super(ASM_OPCODE_VERSION);
            _handlers = handlers;
            _containingResource = containingResource;
        }


        @Override
        public void visit (final int version,
                           final int access,
                           final String name,
                           final String signature,
                           final String superName,
                           final String[] interfaces)
        {
            _ci = new ClassInfo(_containingResource, normalize(name), version, access, signature, normalize(superName), normalize(interfaces));

            _parsedClassNames.add(_ci.getClassName());

            for (Handler h:_handlers)
               h.handle(_ci);
        }


        /**
         * Visit an annotation on a Class
         *
         * @see org.objectweb.asm.ClassVisitor#visitAnnotation(java.lang.String, boolean)
         */
        @Override
        public AnnotationVisitor visitAnnotation (String desc, boolean visible)
        {
            String annotationName = normalize(desc);
            for (Handler h : _handlers)
                h.handle(_ci, annotationName);

            return null;
        }


        /**
         * Visit a method to extract its annotations
         *
         * @see org.objectweb.asm.ClassVisitor#visitMethod(int, java.lang.String, java.lang.String, java.lang.String, java.lang.String[])
         */
        @Override
        public MethodVisitor visitMethod (final int access,
                                          final String name,
                                          final String methodDesc,
                                          final String signature,
                                          final String[] exceptions)
        {

            return new MyMethodVisitor(_handlers, _ci, access, name, methodDesc, signature, exceptions);
        }

        /**
         * Visit a field to extract its annotations
         *
         * @see org.objectweb.asm.ClassVisitor#visitField(int, java.lang.String, java.lang.String, java.lang.String, java.lang.Object)
         */
        @Override
        public FieldVisitor visitField (final int access,
                                        final String fieldName,
                                        final String fieldType,
                                        final String signature,
                                        final Object value)
        {
            return new MyFieldVisitor(_handlers, _ci, access, fieldName, fieldType, signature, value);
        }
    }


    /**
     * True if the class has already been processed, false otherwise
     * @param className
     */
    public boolean isParsed (String className)
    {
        return _parsedClassNames.contains(className);
    }


    /**
     * Parse a given class
     *
     * @param className
     * @param resolver
     * @throws Exception
     */
    public void parse (Set<? extends Handler> handlers, String className, ClassNameResolver resolver)
    throws Exception
    {
        if (className == null)
            return;

        if (!resolver.isExcluded(className))
        {
            if (!isParsed(className) || resolver.shouldOverride(className))
            {
                className = className.replace('.', '/')+".class";
                URL resource = Loader.getResource(this.getClass(), className);
                if (resource!= null)
                {
                    Resource r = Resource.newResource(resource);
                    scanClass(handlers, null, r.getInputStream());
                }
            }
        }
    }


    /**
     * Parse the given class, optionally walking its inheritance hierarchy
     *
     * @param clazz
     * @param resolver
     * @param visitSuperClasses
     * @throws Exception
     */
    public void parse (Set<? extends Handler> handlers, Class<?> clazz, ClassNameResolver resolver, boolean visitSuperClasses)
    throws Exception
    {
        Class<?> cz = clazz;
        while (cz != null)
        {
            if (!resolver.isExcluded(cz.getName()))
            {
                if (!isParsed(cz.getName()) || resolver.shouldOverride(cz.getName()))
                {
                    String nameAsResource = cz.getName().replace('.', '/')+".class";
                    URL resource = Loader.getResource(this.getClass(), nameAsResource);
                    if (resource!= null)
                    {
                        Resource r = Resource.newResource(resource);
                        scanClass(handlers, null, r.getInputStream());
                    }
                }
            }

            if (visitSuperClasses)
                cz = cz.getSuperclass();
            else
                cz = null;
        }
    }


    /**
     * Parse the given classes
     *
     * @param classNames
     * @param resolver
     * @throws Exception
     */
    public void parse (Set<? extends Handler> handlers, String[] classNames, ClassNameResolver resolver)
    throws Exception
    {
        if (classNames == null)
            return;

        parse(handlers, Arrays.asList(classNames), resolver);
    }


    /**
     * Parse the given classes
     *
     * @param classNames
     * @param resolver
     * @throws Exception
     */
    public void parse (Set<? extends Handler> handlers, List<String> classNames, ClassNameResolver resolver)
    throws Exception
    {
        MultiException me = new MultiException();

        for (String s:classNames)
        {
            try
            {
                if ((resolver == null) || (!resolver.isExcluded(s) &&  (!isParsed(s) || resolver.shouldOverride(s))))
                {
                    s = s.replace('.', '/')+".class";
                    URL resource = Loader.getResource(this.getClass(), s);
                    if (resource!= null)
                    {
                        Resource r = Resource.newResource(resource);
                        scanClass(handlers, null, r.getInputStream());
                    }
                }
            }
            catch (Exception e)
            {
                me.add(new RuntimeException("Error scanning class "+s, e));
            }
        }
        me.ifExceptionThrow();
    }


    /**
     * Parse all classes in a directory
     *
     * @param dir
     * @param resolver
     * @throws Exception
     */
    protected void parseDir (Set<? extends Handler> handlers, Resource dir, ClassNameResolver resolver)
    throws Exception
    {
        //skip dirs whose name start with . (ie hidden)
        if (!dir.isDirectory() || !dir.exists() || dir.getName().startsWith("."))
            return;

        if (LOG.isDebugEnabled()) {LOG.debug("Scanning dir {}", dir);};

        MultiException me = new MultiException();

        String[] files=dir.list();
        for (int f=0;files!=null && f<files.length;f++)
        {
            Resource res = dir.addPath(files[f]);
            if (res.isDirectory())
                parseDir(handlers, res, resolver);
            else
            {
                //we've already verified the directories, so just verify the class file name
                File file = res.getFile();
                if (isValidClassFileName((file==null?null:file.getName())))
                {
                    try
                    {
                        String name = res.getName();
                        if ((resolver == null)|| (!resolver.isExcluded(name) && (!isParsed(name) || resolver.shouldOverride(name))))
                        {
                            Resource r = Resource.newResource(res.getURL());
                            if (LOG.isDebugEnabled()) {LOG.debug("Scanning class {}", r);};
                            scanClass(handlers, dir, r.getInputStream());
                        }
                    }
                    catch (Exception ex)
                    {
                        if (LOG.isDebugEnabled()) LOG.debug("Error scanning file "+files[f], ex);
                        me.add(new RuntimeException("Error scanning file "+files[f],ex));
                    }
                }
                else
                {
                   if (LOG.isDebugEnabled()) LOG.debug("Skipping scan on invalid file {}", res);
                }
            }
        }

        me.ifExceptionThrow();
    }


    /**
     * Parse classes in the supplied classloader.
     * Only class files in jar files will be scanned.
     *
     * @param loader
     * @param visitParents
     * @param nullInclusive
     * @param resolver
     * @throws Exception
     */
    public void parse (final Set<? extends Handler> handlers, ClassLoader loader, boolean visitParents, boolean nullInclusive, final ClassNameResolver resolver)
    throws Exception
    {
        if (loader==null)
            return;

        if (!(loader instanceof URLClassLoader))
            return; //can't extract classes?

        final MultiException me = new MultiException();

        JarScanner scanner = new JarScanner()
        {
            @Override
            public void processEntry(URI jarUri, JarEntry entry)
            {
                try
                {
                    parseJarEntry(handlers, Resource.newResource(jarUri), entry, resolver);
                }
                catch (Exception e)
                {
                    me.add(new RuntimeException("Error parsing entry "+entry.getName()+" from jar "+ jarUri, e));
                }
            }

        };

        scanner.scan(null, loader, nullInclusive, visitParents);
        me.ifExceptionThrow();
    }


    /**
     * Parse classes in the supplied uris.
     *
     * @param uris
     * @param resolver
     * @throws Exception
     */
    public void parse (final Set<? extends Handler> handlers, final URI[] uris, final ClassNameResolver resolver)
    throws Exception
    {
        if (uris==null)
            return;

        MultiException me = new MultiException();

        for (URI uri:uris)
        {
            try
            {
                parse(handlers, uri, resolver);
            }
            catch (Exception e)
            {
                me.add(new RuntimeException("Problem parsing classes from "+ uri, e));
            }
        }
        me.ifExceptionThrow();
    }

    /**
     * Parse a particular uri
     * @param uri
     * @param resolver
     * @throws Exception
     */
    public void parse (final Set<? extends Handler> handlers, URI uri, final ClassNameResolver resolver)
    throws Exception
    {
        if (uri == null)
            return;

        parse (handlers, Resource.newResource(uri), resolver);
    }


    /**
     * Parse a resource
     * @param r
     * @param resolver
     * @throws Exception
     */
    public void parse (final Set<? extends Handler> handlers, Resource r, final ClassNameResolver resolver)
    throws Exception
    {
        if (r == null)
            return;

        if (r.exists() && r.isDirectory())
        {
            parseDir(handlers, r, resolver);
            return;
        }

        String fullname = r.toString();
        if (fullname.endsWith(".jar"))
        {
            parseJar(handlers, r, resolver);
            return;
        }

        if (fullname.endsWith(".class"))
        {
            scanClass(handlers, null, r.getInputStream());
            return;
        }

        if (LOG.isDebugEnabled()) LOG.warn("Resource not scannable for classes: {}", r);
    }


    /**
     * Parse a resource that is a jar file.
     *
     * @param jarResource
     * @param resolver
     * @throws Exception
     */
    protected void parseJar (Set<? extends Handler> handlers, Resource jarResource,  final ClassNameResolver resolver)
    throws Exception
    {
        if (jarResource == null)
            return;

        if (jarResource.toString().endsWith(".jar"))
        {
            if (LOG.isDebugEnabled()) {LOG.debug("Scanning jar {}", jarResource);};

            //treat it as a jar that we need to open and scan all entries from
            //TODO alternative impl
            /*
            long start = System.nanoTime();
            Collection<Resource> resources = Resource.newResource("jar:"+jarResource+"!/").getAllResources();
            System.err.println(jarResource+String.valueOf(resources.size())+" resources listed in "+ ((TimeUnit.MILLISECONDS.convert(System.nanoTime()-start, TimeUnit.NANOSECONDS))));
            for (Resource r:resources)
            {
                //skip directories
                if (r.isDirectory())
                    continue;

                String name = r.getName();
                name = name.substring(name.indexOf("!/")+2);

                //check file is a valid class file name
                if (isValidClassFileName(name) && isValidClassFilePath(name))
                {
                    String shortName =  name.replace('/', '.').substring(0,name.length()-6);

                    if ((resolver == null)
                            ||
                        (!resolver.isExcluded(shortName) && (!isParsed(shortName) || resolver.shouldOverride(shortName))))
                    {
                        if (LOG.isDebugEnabled()) {LOG.debug("Scanning class from jar {}", r);};
                        scanClass(handlers, jarResource, r.getInputStream());
                    }
                }
            }
            */

           InputStream in = jarResource.getInputStream();
            if (in==null)
                return;

            MultiException me = new MultiException();

            JarInputStream jar_in = new JarInputStream(in);
            try
            {
                JarEntry entry = jar_in.getNextJarEntry();
                while (entry!=null)
                {
                    try
                    {
                        parseJarEntry(handlers, jarResource, entry, resolver);
                    }
                    catch (Exception e)
                    {
                        me.add(new RuntimeException("Error scanning entry "+entry.getName()+" from jar "+jarResource, e));
                    }
                    entry = jar_in.getNextJarEntry();
                }
            }
            finally
            {
                jar_in.close();
            }
            me.ifExceptionThrow();
        }
    }

    /**
     * Parse a single entry in a jar file
     * @param jar
     * @param entry
     * @param resolver
     * @throws Exception
     */
    protected void parseJarEntry (Set<? extends Handler> handlers, Resource jar, JarEntry entry, final ClassNameResolver resolver)
    throws Exception
    {
        if (jar == null || entry == null)
            return;

        //skip directories
        if (entry.isDirectory())
            return;

        String name = entry.getName();

        //check file is a valid class file name
        if (isValidClassFileName(name) && isValidClassFilePath(name))
        {
            String shortName =  name.replace('/', '.').substring(0,name.length()-6);

            if ((resolver == null)
                    ||
                (!resolver.isExcluded(shortName) && (!isParsed(shortName) || resolver.shouldOverride(shortName))))
            {
                Resource clazz = Resource.newResource("jar:"+jar.getURI()+"!/"+name);
                if (LOG.isDebugEnabled()) {LOG.debug("Scanning class from jar {}", clazz);};
                scanClass(handlers, jar, clazz.getInputStream());
            }
        }
    }


    /**
     * Use ASM on a class
     *
     * @param containingResource the dir or jar that the class is contained within, can be null if not known
     * @param is
     * @throws IOException
     */
    protected void scanClass (Set<? extends Handler> handlers, Resource containingResource, InputStream is)
    throws IOException
    {
        ClassReader reader = new ClassReader(is);
        reader.accept(new MyClassVisitor(handlers, containingResource), ClassReader.SKIP_CODE|ClassReader.SKIP_DEBUG|ClassReader.SKIP_FRAMES);
    }

    /**
     * Check that the given path represents a valid class file name.
     * The check is fairly cursory, checking that:
     * <ul>
     * <li> the name ends with .class</li>
     * <li> it isn't a dot file or in a hidden directory </li>
     * <li> the name of the class at least begins with a valid identifier for a class name </li>
     * </ul>
     * @param name
     * @return
     */
    private boolean isValidClassFileName (String name)
    {
        //no name cannot be valid
        if (name == null || name.length()==0)
            return false;

        //skip anything that is not a class file
        if (!name.toLowerCase(Locale.ENGLISH).endsWith(".class"))
        {
            if (LOG.isDebugEnabled()) LOG.debug("Not a class: {}",name);
            return false;
        }

         //skip any classfiles that are not a valid java identifier
         int c0 = 0;
         int ldir = name.lastIndexOf('/', name.length()-6);
         c0 = (ldir > -1 ? ldir+1 : c0);
         if (!Character.isJavaIdentifierStart(name.charAt(c0)))
         {
             if (LOG.isDebugEnabled()) LOG.debug("Not a java identifier: {}"+name);
             return false;
         }

         return true;
     }


     /**
      * Check that the given path does not contain hidden directories
      *
      * @param path
      * @return
      */
     private boolean isValidClassFilePath (String path)
     {
         //no path is not valid
         if (path == null || path.length()==0)
             return false;

         //skip any classfiles that are in a hidden directory
         if (path.startsWith(".") || path.contains("/."))
         {
             if (LOG.isDebugEnabled()) LOG.debug("Contains hidden dirs: {}"+path);
             return false;
         }

         return true;
     }
 }