org.apache.hadoop.classification.tools.RootDocProcessor Maven / Gradle / Ivy

Go to download
/*
 * Licensed to the Apache Software Foundation (ASF) under one
 * or more contributor license agreements.  See the NOTICE file
 * distributed with this work for additional information
 * regarding copyright ownership.  The ASF licenses this file
 * to you under the Apache License, Version 2.0 (the
 * "License"); you may not use this file except in compliance
 * with the License.  You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
package org.apache.hadoop.classification.tools;

import com.sun.javadoc.AnnotationDesc;
import com.sun.javadoc.AnnotationTypeDoc;
import com.sun.javadoc.ClassDoc;
import com.sun.javadoc.ConstructorDoc;
import com.sun.javadoc.Doc;
import com.sun.javadoc.FieldDoc;
import com.sun.javadoc.MethodDoc;
import com.sun.javadoc.PackageDoc;
import com.sun.javadoc.ProgramElementDoc;
import com.sun.javadoc.RootDoc;

import java.lang.reflect.Array;
import java.lang.reflect.InvocationHandler;
import java.lang.reflect.InvocationTargetException;
import java.lang.reflect.Method;
import java.lang.reflect.Proxy;
import java.util.ArrayList;
import java.util.List;
import java.util.Map;
import java.util.WeakHashMap;

import org.apache.hadoop.classification.InterfaceAudience;
import org.apache.hadoop.classification.InterfaceStability;

/**
 * Process the {@link RootDoc} by substituting with (nested) proxy objects that
 * exclude elements with Private or LimitedPrivate annotations.
 * 
 * Based on code from http://www.sixlegs.com/blog/java/exclude-javadoc-tag.html.
 */
class RootDocProcessor {
  
  static String stability = StabilityOptions.UNSTABLE_OPTION;
  static boolean treatUnannotatedClassesAsPrivate = false;
  
  public static RootDoc process(RootDoc root) {
    return (RootDoc) process(root, RootDoc.class);
  }
  
  private static Object process(Object obj, Class type) { 
    if (obj == null) { 
      return null; 
    } 
    Class cls = obj.getClass(); 
    if (cls.getName().startsWith("com.sun.")) { 
      return getProxy(obj); 
    } else if (obj instanceof Object[]) { 
      Class componentType = type.isArray() ? type.getComponentType() 
	  : cls.getComponentType();
      Object[] array = (Object[]) obj;
      Object[] newArray = (Object[]) Array.newInstance(componentType,
	  array.length); 
      for (int i = 0; i < array.length; ++i) {
        newArray[i] = process(array[i], componentType);
      }
      return newArray;
    } 
    return obj; 
  }
  
  private static Map proxies =
    new WeakHashMap(); 
  
  private static Object getProxy(Object obj) { 
    Object proxy = proxies.get(obj); 
    if (proxy == null) { 
      proxy = Proxy.newProxyInstance(obj.getClass().getClassLoader(), 
        obj.getClass().getInterfaces(), new ExcludeHandler(obj)); 
      proxies.put(obj, proxy); 
    } 
    return proxy; 
  } 

  private static class ExcludeHandler implements InvocationHandler {
    private Object target;

    public ExcludeHandler(Object target) {
      this.target = target;
    }
    
    public Object invoke(Object proxy, Method method, Object[] args)
	throws Throwable {
      String methodName = method.getName();
      if (target instanceof Doc) {
	if (methodName.equals("isIncluded")) {
	  Doc doc = (Doc) target;
	  return !exclude(doc) && doc.isIncluded();
	}
	if (target instanceof RootDoc) {
	  if (methodName.equals("classes")) {
	    return filter(((RootDoc) target).classes(), ClassDoc.class);
	  } else if (methodName.equals("specifiedClasses")) {
	    return filter(((RootDoc) target).specifiedClasses(), ClassDoc.class);
	  } else if (methodName.equals("specifiedPackages")) {
	    return filter(((RootDoc) target).specifiedPackages(), PackageDoc.class);
	  }
	} else if (target instanceof ClassDoc) {
	  if (isFiltered(args)) {
	    if (methodName.equals("methods")) {
	      return filter(((ClassDoc) target).methods(true), MethodDoc.class);
	    } else if (methodName.equals("fields")) {
	      return filter(((ClassDoc) target).fields(true), FieldDoc.class);
	    } else if (methodName.equals("innerClasses")) {
	      return filter(((ClassDoc) target).innerClasses(true),
		  ClassDoc.class);
	    } else if (methodName.equals("constructors")) {
	      return filter(((ClassDoc) target).constructors(true),
		  ConstructorDoc.class);
	    }
	  }
	} else if (target instanceof PackageDoc) {
	  if (methodName.equals("allClasses")) {
	    if (isFiltered(args)) {
	      return filter(((PackageDoc) target).allClasses(true),
		ClassDoc.class);
	    } else {
	      return filter(((PackageDoc) target).allClasses(), ClassDoc.class);  
	    }
	  } else if (methodName.equals("annotationTypes")) {
	    return filter(((PackageDoc) target).annotationTypes(),
		AnnotationTypeDoc.class);
	  } else if (methodName.equals("enums")) {
	    return filter(((PackageDoc) target).enums(),
		ClassDoc.class);
	  } else if (methodName.equals("errors")) {
	    return filter(((PackageDoc) target).errors(),
		ClassDoc.class);
	  } else if (methodName.equals("exceptions")) {
	    return filter(((PackageDoc) target).exceptions(),
		ClassDoc.class);
	  } else if (methodName.equals("interfaces")) {
	    return filter(((PackageDoc) target).interfaces(),
		ClassDoc.class);
	  } else if (methodName.equals("ordinaryClasses")) {
	    return filter(((PackageDoc) target).ordinaryClasses(),
		ClassDoc.class);
	  }
	}
      }

      if (args != null) {
	if (methodName.equals("compareTo") || methodName.equals("equals")
	    || methodName.equals("overrides")
	    || methodName.equals("subclassOf")) {
	  args[0] = unwrap(args[0]);
	}
      }
      try {
	return process(method.invoke(target, args), method.getReturnType());
      } catch (InvocationTargetException e) {
	throw e.getTargetException();
      }
    }
      
    private static boolean exclude(Doc doc) {
      AnnotationDesc[] annotations = null;
      if (doc instanceof ProgramElementDoc) {
	annotations = ((ProgramElementDoc) doc).annotations();
      } else if (doc instanceof PackageDoc) {
	annotations = ((PackageDoc) doc).annotations();
      }
      if (annotations != null) {
	for (AnnotationDesc annotation : annotations) {
	  String qualifiedTypeName = annotation.annotationType().qualifiedTypeName();
	  if (qualifiedTypeName.equals(
	        InterfaceAudience.Private.class.getCanonicalName())
	    || qualifiedTypeName.equals(
                InterfaceAudience.LimitedPrivate.class.getCanonicalName())) {
	    return true;
	  }
	  if (stability.equals(StabilityOptions.EVOLVING_OPTION)) {
	    if (qualifiedTypeName.equals(
		InterfaceStability.Unstable.class.getCanonicalName())) {
	      return true;
	    }
	  }
	  if (stability.equals(StabilityOptions.STABLE_OPTION)) {
	    if (qualifiedTypeName.equals(
		InterfaceStability.Unstable.class.getCanonicalName())
              || qualifiedTypeName.equals(
  		InterfaceStability.Evolving.class.getCanonicalName())) {
	      return true;
	    }
	  }
	}
        for (AnnotationDesc annotation : annotations) {
          String qualifiedTypeName =
            annotation.annotationType().qualifiedTypeName();
          if (qualifiedTypeName.equals(
              InterfaceAudience.Public.class.getCanonicalName())) {
            return false;
          }
        }
      }
      if (treatUnannotatedClassesAsPrivate) {
        return doc.isClass() || doc.isInterface() || doc.isAnnotationType();
      }
      return false;
    }
      
    private static Object[] filter(Doc[] array, Class componentType) {
      if (array == null || array.length == 0) {
	return array;
      }
      List