YETUS-126 break audience-annotation into multi-module and isolate jdiff add-on.
Signed-off-by: Allen Wittenauer <[email protected]> Project: http://git-wip-us.apache.org/repos/asf/yetus/repo Commit: http://git-wip-us.apache.org/repos/asf/yetus/commit/35718141 Tree: http://git-wip-us.apache.org/repos/asf/yetus/tree/35718141 Diff: http://git-wip-us.apache.org/repos/asf/yetus/diff/35718141 Branch: refs/heads/YETUS-83 Commit: 3571814104ae225cf2445279f5805f7f8f1ee20b Parents: 1d78a3f Author: Sean Busbey <[email protected]> Authored: Sat Oct 24 01:43:13 2015 -0500 Committer: Allen Wittenauer <[email protected]> Committed: Mon Oct 26 16:16:08 2015 -0700 ---------------------------------------------------------------------- .../audience-annotations-jdiff/pom.xml | 58 +++++ .../ExcludePrivateAnnotationsJDiffDoclet.java | 64 +++++ .../audience-annotations/pom.xml | 46 ++++ .../yetus/audience/InterfaceAudience.java | 74 ++++++ .../yetus/audience/InterfaceStability.java | 65 +++++ ...ExcludePrivateAnnotationsStandardDoclet.java | 63 +++++ .../IncludePublicAnnotationsStandardDoclet.java | 68 +++++ .../yetus/audience/tools/RootDocProcessor.java | 247 +++++++++++++++++++ .../yetus/audience/tools/StabilityOptions.java | 70 ++++++ audience-annotations-component/pom.xml | 40 +++ audience-annotations/pom.xml | 53 ---- .../yetus/audience/InterfaceAudience.java | 74 ------ .../yetus/audience/InterfaceStability.java | 65 ----- .../ExcludePrivateAnnotationsJDiffDoclet.java | 64 ----- ...ExcludePrivateAnnotationsStandardDoclet.java | 63 ----- .../IncludePublicAnnotationsStandardDoclet.java | 68 ----- .../yetus/audience/tools/RootDocProcessor.java | 247 ------------------- .../yetus/audience/tools/StabilityOptions.java | 70 ------ .../yetus/audience/tools/package-info.java | 18 -- 19 files changed, 795 insertions(+), 722 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/yetus/blob/35718141/audience-annotations-component/audience-annotations-jdiff/pom.xml ---------------------------------------------------------------------- diff --git a/audience-annotations-component/audience-annotations-jdiff/pom.xml b/audience-annotations-component/audience-annotations-jdiff/pom.xml new file mode 100644 index 0000000..63f6fb9 --- /dev/null +++ b/audience-annotations-component/audience-annotations-jdiff/pom.xml @@ -0,0 +1,58 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + 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. +--> +<project xmlns="http://maven.apache.org/POM/4.0.0"; + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; + xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 + http://maven.apache.org/xsd/maven-4.0.0.xsd";> + <modelVersion>4.0.0</modelVersion> + <parent> + <groupId>org.apache.yetus</groupId> + <artifactId>yetus-project</artifactId> + <version>0.1.0-SNAPSHOT</version> + <relativePath>../../yetus-project</relativePath> + </parent> + <artifactId>audience-annotations-jdiff</artifactId> + <description>Tools for managing JDiff generated javadocs</description> + <name>Apache Yetus - Audience Annotations JDiff Doclet</name> + <packaging>jar</packaging> + + <dependencies> + <dependency> + <groupId>org.apache.yetus</groupId> + <artifactId>audience-annotations</artifactId> + <version>${project.version}</version> + </dependency> + <dependency> + <groupId>jdiff</groupId> + <artifactId>jdiff</artifactId> + <version>1.0.9</version> + <scope>provided</scope> + <optional>true</optional> + </dependency> + <dependency> + <!-- Version and location set in project pom --> + <groupId>jdk.tools</groupId> + <artifactId>jdk.tools</artifactId> + <scope>system</scope> + <!-- Mark as optional so that it isn't taken transitively --> + <optional>true</optional> + </dependency> + </dependencies> +</project> http://git-wip-us.apache.org/repos/asf/yetus/blob/35718141/audience-annotations-component/audience-annotations-jdiff/src/main/java/org/apache/yetus/audience/tools/ExcludePrivateAnnotationsJDiffDoclet.java ---------------------------------------------------------------------- diff --git a/audience-annotations-component/audience-annotations-jdiff/src/main/java/org/apache/yetus/audience/tools/ExcludePrivateAnnotationsJDiffDoclet.java b/audience-annotations-component/audience-annotations-jdiff/src/main/java/org/apache/yetus/audience/tools/ExcludePrivateAnnotationsJDiffDoclet.java new file mode 100644 index 0000000..83cda3d --- /dev/null +++ b/audience-annotations-component/audience-annotations-jdiff/src/main/java/org/apache/yetus/audience/tools/ExcludePrivateAnnotationsJDiffDoclet.java @@ -0,0 +1,64 @@ +/* + * 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.yetus.audience.tools; + +import com.sun.javadoc.DocErrorReporter; +import com.sun.javadoc.LanguageVersion; +import com.sun.javadoc.RootDoc; + +import jdiff.JDiff; + +import org.apache.yetus.audience.InterfaceAudience; +import org.apache.yetus.audience.InterfaceStability; + +/** + * A <a href="http://java.sun.com/javase/6/docs/jdk/api/javadoc/doclet/";>Doclet</a> + * for excluding elements that are annotated with + * {@link org.apache.yetus.audience.InterfaceAudience.Private} or + * {@link org.apache.yetus.audience.InterfaceAudience.LimitedPrivate}. + * It delegates to the JDiff Doclet, and takes the same options. + */ [email protected] [email protected] +public class ExcludePrivateAnnotationsJDiffDoclet { + + public static LanguageVersion languageVersion() { + return LanguageVersion.JAVA_1_5; + } + + public static boolean start(RootDoc root) { + System.out.println( + ExcludePrivateAnnotationsJDiffDoclet.class.getSimpleName()); + return JDiff.start(RootDocProcessor.process(root)); + } + + public static int optionLength(String option) { + Integer length = StabilityOptions.optionLength(option); + if (length != null) { + return length; + } + return JDiff.optionLength(option); + } + + public static boolean validOptions(String[][] options, + DocErrorReporter reporter) { + StabilityOptions.validOptions(options, reporter); + String[][] filteredOptions = StabilityOptions.filterOptions(options); + return JDiff.validOptions(filteredOptions, reporter); + } +} http://git-wip-us.apache.org/repos/asf/yetus/blob/35718141/audience-annotations-component/audience-annotations/pom.xml ---------------------------------------------------------------------- diff --git a/audience-annotations-component/audience-annotations/pom.xml b/audience-annotations-component/audience-annotations/pom.xml new file mode 100644 index 0000000..4c7f0d7 --- /dev/null +++ b/audience-annotations-component/audience-annotations/pom.xml @@ -0,0 +1,46 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + 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. +--> +<project xmlns="http://maven.apache.org/POM/4.0.0"; + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; + xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 + http://maven.apache.org/xsd/maven-4.0.0.xsd";> + <modelVersion>4.0.0</modelVersion> + <parent> + <groupId>org.apache.yetus</groupId> + <artifactId>yetus-project</artifactId> + <version>0.1.0-SNAPSHOT</version> + <relativePath>../../yetus-project</relativePath> + </parent> + <artifactId>audience-annotations</artifactId> + <description>Annotations for defining API boundaries and tools for managing javadocs</description> + <name>Apache Yetus - Audience Annotations</name> + <packaging>jar</packaging> + + <dependencies> + <dependency> + <!-- Version and location set in project pom --> + <groupId>jdk.tools</groupId> + <artifactId>jdk.tools</artifactId> + <scope>system</scope> + <!-- Mark as optional so that it isn't taken transitively --> + <optional>true</optional> + </dependency> + </dependencies> +</project> http://git-wip-us.apache.org/repos/asf/yetus/blob/35718141/audience-annotations-component/audience-annotations/src/main/java/org/apache/yetus/audience/InterfaceAudience.java ---------------------------------------------------------------------- diff --git a/audience-annotations-component/audience-annotations/src/main/java/org/apache/yetus/audience/InterfaceAudience.java b/audience-annotations-component/audience-annotations/src/main/java/org/apache/yetus/audience/InterfaceAudience.java new file mode 100644 index 0000000..1441767 --- /dev/null +++ b/audience-annotations-component/audience-annotations/src/main/java/org/apache/yetus/audience/InterfaceAudience.java @@ -0,0 +1,74 @@ +/* + * 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.yetus.audience; + +import java.lang.annotation.Documented; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; + +/** + * Annotation to inform users of a package, class or method's intended audience. + * Currently the audience can be {@link Public}, {@link LimitedPrivate} or + * {@link Private}. <br> + * All public classes must have InterfaceAudience annotation. <br> + * <ul> + * <li>Public classes that are not marked with this annotation must be + * considered by default as {@link Private}.</li> + * + * <li>External applications must only use classes that are marked + * {@link Public}. Avoid using non public classes as these classes + * could be removed or change in incompatible ways.</li> + * + * <li>Some projects may choose to give special consideration to related + * projects. Such consideration can be done by using the {@link LimitedPrivate} + * annotation with a named set of projects.</li> + * + * <li> Methods may have a different annotation that it is more restrictive + * compared to the audience classification of the class. Example: A class + * might be {@link Public}, but a method may be {@link LimitedPrivate} + * </li></ul> + */ [email protected] [email protected] +public class InterfaceAudience { + /** + * Intended for use by any project or application. + */ + @Documented + @Retention(RetentionPolicy.RUNTIME) + public @interface Public {}; + + /** + * Intended only for the project(s) specified in the annotation. + * For example, "Hadoop Common", "HDFS", "MapReduce", "ZooKeeper", "HBase". + */ + @Documented + @Retention(RetentionPolicy.RUNTIME) + public @interface LimitedPrivate { + String[] value(); + }; + + /** + * Intended for use only within a given project. + */ + @Documented + @Retention(RetentionPolicy.RUNTIME) + public @interface Private {}; + + private InterfaceAudience() {} // Audience can't exist on its own +} http://git-wip-us.apache.org/repos/asf/yetus/blob/35718141/audience-annotations-component/audience-annotations/src/main/java/org/apache/yetus/audience/InterfaceStability.java ---------------------------------------------------------------------- diff --git a/audience-annotations-component/audience-annotations/src/main/java/org/apache/yetus/audience/InterfaceStability.java b/audience-annotations-component/audience-annotations/src/main/java/org/apache/yetus/audience/InterfaceStability.java new file mode 100644 index 0000000..93be2a9 --- /dev/null +++ b/audience-annotations-component/audience-annotations/src/main/java/org/apache/yetus/audience/InterfaceStability.java @@ -0,0 +1,65 @@ +/* + * 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.yetus.audience; + +import java.lang.annotation.Documented; +import java.lang.annotation.Retention; +import java.lang.annotation.RetentionPolicy; + +import org.apache.yetus.audience.InterfaceAudience.LimitedPrivate; +import org.apache.yetus.audience.InterfaceAudience.Private; +import org.apache.yetus.audience.InterfaceAudience.Public; + +/** + * Annotation to inform users of how much to rely on a particular package, + * class or method not changing over time. Currently the stability can be + * {@link Stable}, {@link Evolving} or {@link Unstable}. <br> + * + * <ul><li>All classes that are annotated with {@link Public} or + * {@link LimitedPrivate} must have InterfaceStability annotation. </li> + * <li>Classes that are {@link Private} are to be considered unstable unless + * a different InterfaceStability annotation states otherwise.</li> + * <li>Incompatible changes must not be made to classes marked as stable.</li> + * </ul> + */ [email protected] [email protected] +public class InterfaceStability { + /** + * Can evolve while retaining compatibility for minor release boundaries.; + * can break compatibility only at major release (ie. at m.0). + */ + @Documented + @Retention(RetentionPolicy.RUNTIME) + public @interface Stable {}; + + /** + * Evolving, but can break compatibility at minor release (i.e. m.x) + */ + @Documented + @Retention(RetentionPolicy.RUNTIME) + public @interface Evolving {}; + + /** + * No guarantee is provided as to reliability or stability across any + * level of release granularity. + */ + @Documented + @Retention(RetentionPolicy.RUNTIME) + public @interface Unstable {}; +} http://git-wip-us.apache.org/repos/asf/yetus/blob/35718141/audience-annotations-component/audience-annotations/src/main/java/org/apache/yetus/audience/tools/ExcludePrivateAnnotationsStandardDoclet.java ---------------------------------------------------------------------- diff --git a/audience-annotations-component/audience-annotations/src/main/java/org/apache/yetus/audience/tools/ExcludePrivateAnnotationsStandardDoclet.java b/audience-annotations-component/audience-annotations/src/main/java/org/apache/yetus/audience/tools/ExcludePrivateAnnotationsStandardDoclet.java new file mode 100644 index 0000000..860f25d --- /dev/null +++ b/audience-annotations-component/audience-annotations/src/main/java/org/apache/yetus/audience/tools/ExcludePrivateAnnotationsStandardDoclet.java @@ -0,0 +1,63 @@ +/* + * 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.yetus.audience.tools; + +import com.sun.javadoc.DocErrorReporter; +import com.sun.javadoc.LanguageVersion; +import com.sun.javadoc.RootDoc; +import com.sun.tools.doclets.standard.Standard; + +import org.apache.yetus.audience.InterfaceAudience; +import org.apache.yetus.audience.InterfaceStability; + +/** + * A <a href="http://java.sun.com/javase/6/docs/jdk/api/javadoc/doclet/";>Doclet</a> + * for excluding elements that are annotated with + * {@link org.apache.yetus.audience.InterfaceAudience.Private} or + * {@link org.apache.yetus.audience.InterfaceAudience.LimitedPrivate}. + * It delegates to the Standard Doclet, and takes the same options. + */ [email protected] [email protected] +public class ExcludePrivateAnnotationsStandardDoclet { + + public static LanguageVersion languageVersion() { + return LanguageVersion.JAVA_1_5; + } + + public static boolean start(RootDoc root) { + System.out.println( + ExcludePrivateAnnotationsStandardDoclet.class.getSimpleName()); + return Standard.start(RootDocProcessor.process(root)); + } + + public static int optionLength(String option) { + Integer length = StabilityOptions.optionLength(option); + if (length != null) { + return length; + } + return Standard.optionLength(option); + } + + public static boolean validOptions(String[][] options, + DocErrorReporter reporter) { + StabilityOptions.validOptions(options, reporter); + String[][] filteredOptions = StabilityOptions.filterOptions(options); + return Standard.validOptions(filteredOptions, reporter); + } +} http://git-wip-us.apache.org/repos/asf/yetus/blob/35718141/audience-annotations-component/audience-annotations/src/main/java/org/apache/yetus/audience/tools/IncludePublicAnnotationsStandardDoclet.java ---------------------------------------------------------------------- diff --git a/audience-annotations-component/audience-annotations/src/main/java/org/apache/yetus/audience/tools/IncludePublicAnnotationsStandardDoclet.java b/audience-annotations-component/audience-annotations/src/main/java/org/apache/yetus/audience/tools/IncludePublicAnnotationsStandardDoclet.java new file mode 100644 index 0000000..d21c20f --- /dev/null +++ b/audience-annotations-component/audience-annotations/src/main/java/org/apache/yetus/audience/tools/IncludePublicAnnotationsStandardDoclet.java @@ -0,0 +1,68 @@ +/* + * 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.yetus.audience.tools; + +import com.sun.javadoc.DocErrorReporter; +import com.sun.javadoc.LanguageVersion; +import com.sun.javadoc.RootDoc; +import com.sun.tools.doclets.standard.Standard; + +import org.apache.yetus.audience.InterfaceAudience; +import org.apache.yetus.audience.InterfaceStability; + +/** + * A <a href="http://java.sun.com/javase/6/docs/jdk/api/javadoc/doclet/";>Doclet</a> + * that only includes class-level elements that are annotated with + * {@link org.apache.yetus.audience.InterfaceAudience.Public}. + * Class-level elements with no annotation are excluded. + * In addition, all elements that are annotated with + * {@link org.apache.yetus.audience.InterfaceAudience.Private} or + * {@link org.apache.yetus.audience.InterfaceAudience.LimitedPrivate} + * are also excluded. + * It delegates to the Standard Doclet, and takes the same options. + */ [email protected] [email protected] +public class IncludePublicAnnotationsStandardDoclet { + + public static LanguageVersion languageVersion() { + return LanguageVersion.JAVA_1_5; + } + + public static boolean start(RootDoc root) { + System.out.println( + IncludePublicAnnotationsStandardDoclet.class.getSimpleName()); + RootDocProcessor.treatUnannotatedClassesAsPrivate = true; + return Standard.start(RootDocProcessor.process(root)); + } + + public static int optionLength(String option) { + Integer length = StabilityOptions.optionLength(option); + if (length != null) { + return length; + } + return Standard.optionLength(option); + } + + public static boolean validOptions(String[][] options, + DocErrorReporter reporter) { + StabilityOptions.validOptions(options, reporter); + String[][] filteredOptions = StabilityOptions.filterOptions(options); + return Standard.validOptions(filteredOptions, reporter); + } +} http://git-wip-us.apache.org/repos/asf/yetus/blob/35718141/audience-annotations-component/audience-annotations/src/main/java/org/apache/yetus/audience/tools/RootDocProcessor.java ---------------------------------------------------------------------- diff --git a/audience-annotations-component/audience-annotations/src/main/java/org/apache/yetus/audience/tools/RootDocProcessor.java b/audience-annotations-component/audience-annotations/src/main/java/org/apache/yetus/audience/tools/RootDocProcessor.java new file mode 100644 index 0000000..46d7fac --- /dev/null +++ b/audience-annotations-component/audience-annotations/src/main/java/org/apache/yetus/audience/tools/RootDocProcessor.java @@ -0,0 +1,247 @@ +/* + * 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.yetus.audience.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.yetus.audience.InterfaceAudience; +import org.apache.yetus.audience.InterfaceStability; + +/** + * Process the {@link RootDoc} by substituting with (nested) proxy objects that + * exclude elements with Private or LimitedPrivate annotations. + * <p> + * 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<Object, Object> proxies = + new WeakHashMap<Object, Object>(); + + 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; + } + + @Override + 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<Object> list = new ArrayList<Object>(array.length); + for (Doc entry : array) { + if (!exclude(entry)) { + list.add(process(entry, componentType)); + } + } + return list.toArray((Object[]) Array.newInstance(componentType, list + .size())); + } + + private Object unwrap(Object proxy) { + if (proxy instanceof Proxy) + return ((ExcludeHandler) Proxy.getInvocationHandler(proxy)).target; + return proxy; + } + + private boolean isFiltered(Object[] args) { + return args != null && Boolean.TRUE.equals(args[0]); + } + + } + +} http://git-wip-us.apache.org/repos/asf/yetus/blob/35718141/audience-annotations-component/audience-annotations/src/main/java/org/apache/yetus/audience/tools/StabilityOptions.java ---------------------------------------------------------------------- diff --git a/audience-annotations-component/audience-annotations/src/main/java/org/apache/yetus/audience/tools/StabilityOptions.java b/audience-annotations-component/audience-annotations/src/main/java/org/apache/yetus/audience/tools/StabilityOptions.java new file mode 100644 index 0000000..c22e308 --- /dev/null +++ b/audience-annotations-component/audience-annotations/src/main/java/org/apache/yetus/audience/tools/StabilityOptions.java @@ -0,0 +1,70 @@ +/* + * 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.yetus.audience.tools; + +import com.sun.javadoc.DocErrorReporter; + +import java.util.ArrayList; +import java.util.List; +import java.util.Locale; + +class StabilityOptions { + public static final String STABLE_OPTION = "-stable"; + public static final String EVOLVING_OPTION = "-evolving"; + public static final String UNSTABLE_OPTION = "-unstable"; + + public static Integer optionLength(String option) { + String opt = option.toLowerCase(Locale.ENGLISH); + if (opt.equals(UNSTABLE_OPTION)) return 1; + if (opt.equals(EVOLVING_OPTION)) return 1; + if (opt.equals(STABLE_OPTION)) return 1; + return null; + } + + public static void validOptions(String[][] options, + DocErrorReporter reporter) { + for (int i = 0; i < options.length; i++) { + String opt = options[i][0].toLowerCase(Locale.ENGLISH); + if (opt.equals(UNSTABLE_OPTION)) { + RootDocProcessor.stability = UNSTABLE_OPTION; + } else if (opt.equals(EVOLVING_OPTION)) { + RootDocProcessor.stability = EVOLVING_OPTION; + } else if (opt.equals(STABLE_OPTION)) { + RootDocProcessor.stability = STABLE_OPTION; + } + } + } + + public static String[][] filterOptions(String[][] options) { + List<String[]> optionsList = new ArrayList<String[]>(); + for (int i = 0; i < options.length; i++) { + if (!options[i][0].equalsIgnoreCase(UNSTABLE_OPTION) + && !options[i][0].equalsIgnoreCase(EVOLVING_OPTION) + && !options[i][0].equalsIgnoreCase(STABLE_OPTION)) { + optionsList.add(options[i]); + } + } + String[][] filteredOptions = new String[optionsList.size()][]; + int i = 0; + for (String[] option : optionsList) { + filteredOptions[i++] = option; + } + return filteredOptions; + } + +} http://git-wip-us.apache.org/repos/asf/yetus/blob/35718141/audience-annotations-component/pom.xml ---------------------------------------------------------------------- diff --git a/audience-annotations-component/pom.xml b/audience-annotations-component/pom.xml new file mode 100644 index 0000000..c187de2 --- /dev/null +++ b/audience-annotations-component/pom.xml @@ -0,0 +1,40 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!-- + 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. +--> +<project xmlns="http://maven.apache.org/POM/4.0.0"; + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; + xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 + http://maven.apache.org/xsd/maven-4.0.0.xsd";> + <modelVersion>4.0.0</modelVersion> + <parent> + <groupId>org.apache.yetus</groupId> + <artifactId>yetus-project</artifactId> + <version>0.1.0-SNAPSHOT</version> + <relativePath>../yetus-project</relativePath> + </parent> + <artifactId>audience-annotations-component</artifactId> + <description>Annotations for defining API boundaries and tools for managing javadocs</description> + <name>Apache Yetus - Audience Annotations Component</name> + <packaging>pom</packaging> + + <modules> + <module>audience-annotations</module> + <module>audience-annotations-jdiff</module> + </modules> +</project> http://git-wip-us.apache.org/repos/asf/yetus/blob/35718141/audience-annotations/pom.xml ---------------------------------------------------------------------- diff --git a/audience-annotations/pom.xml b/audience-annotations/pom.xml deleted file mode 100644 index 040d9b3..0000000 --- a/audience-annotations/pom.xml +++ /dev/null @@ -1,53 +0,0 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!-- - 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. ---> -<project xmlns="http://maven.apache.org/POM/4.0.0"; - xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"; - xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 - http://maven.apache.org/xsd/maven-4.0.0.xsd";> - <modelVersion>4.0.0</modelVersion> - <parent> - <groupId>org.apache.yetus</groupId> - <artifactId>yetus-project</artifactId> - <version>0.1.0-SNAPSHOT</version> - <relativePath>../yetus-project</relativePath> - </parent> - <artifactId>audience-annotations</artifactId> - <description>Annotations for defining API boundaries and tools for managing javadocs</description> - <name>Apache Yetus - Audience Annotations</name> - <packaging>jar</packaging> - - <dependencies> - <dependency> - <groupId>jdiff</groupId> - <artifactId>jdiff</artifactId> - <version>1.0.9</version> - <scope>provided</scope> - <optional>true</optional> - </dependency> - <dependency> - <!-- Version and location set in project pom --> - <groupId>jdk.tools</groupId> - <artifactId>jdk.tools</artifactId> - <scope>system</scope> - <!-- Mark as optional so that it isn't taken transitively --> - <optional>true</optional> - </dependency> - </dependencies> -</project> http://git-wip-us.apache.org/repos/asf/yetus/blob/35718141/audience-annotations/src/main/java/org/apache/yetus/audience/InterfaceAudience.java ---------------------------------------------------------------------- diff --git a/audience-annotations/src/main/java/org/apache/yetus/audience/InterfaceAudience.java b/audience-annotations/src/main/java/org/apache/yetus/audience/InterfaceAudience.java deleted file mode 100644 index e618040..0000000 --- a/audience-annotations/src/main/java/org/apache/yetus/audience/InterfaceAudience.java +++ /dev/null @@ -1,74 +0,0 @@ -/* - * 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.yetus.audience; - -import java.lang.annotation.Documented; -import java.lang.annotation.Retention; -import java.lang.annotation.RetentionPolicy; - -/** - * Annotation to inform users of a package, class or method's intended audience. - * Currently the audience can be {@link Public}, {@link LimitedPrivate} or - * {@link Private}. <br> - * All public classes must have InterfaceAudience annotation. <br> - * <ul> - * <li>Public classes that are not marked with this annotation must be - * considered by default as {@link Private}.</li> - * - * <li>External applications must only use classes that are marked - * {@link Public}. Avoid using non public classes as these classes - * could be removed or change in incompatible ways.</li> - * - * <li>Some projects may choose to give special consideration to related - * projects. Such consideration can be done by using the {@link LimitedPrivate} - * annotation with a named set of projects.</li> - * - * <li> Methods may have a different annotation that it is more restrictive - * compared to the audience classification of the class. Example: A class - * might be {@link Public}, but a method may be {@link LimitedPrivate} - * </li></ul> - */ [email protected] [email protected] -public class InterfaceAudience { - /** - * Intended for use by any project or application. - */ - @Documented - @Retention(RetentionPolicy.RUNTIME) - public @interface Public {}; - - /** - * Intended only for the project(s) specified in the annotation. - * For example, "Hadoop Common", "HDFS", "MapReduce", "ZooKeeper", "HBase". - */ - @Documented - @Retention(RetentionPolicy.RUNTIME) - public @interface LimitedPrivate { - String[] value(); - }; - - /** - * Intended for use only within a given project. - */ - @Documented - @Retention(RetentionPolicy.RUNTIME) - public @interface Private {}; - - private InterfaceAudience() {} // Audience can't exist on its own -} http://git-wip-us.apache.org/repos/asf/yetus/blob/35718141/audience-annotations/src/main/java/org/apache/yetus/audience/InterfaceStability.java ---------------------------------------------------------------------- diff --git a/audience-annotations/src/main/java/org/apache/yetus/audience/InterfaceStability.java b/audience-annotations/src/main/java/org/apache/yetus/audience/InterfaceStability.java deleted file mode 100644 index 4942221..0000000 --- a/audience-annotations/src/main/java/org/apache/yetus/audience/InterfaceStability.java +++ /dev/null @@ -1,65 +0,0 @@ -/* - * 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.yetus.audience; - -import java.lang.annotation.Documented; -import java.lang.annotation.Retention; -import java.lang.annotation.RetentionPolicy; - -import org.apache.yetus.audience.InterfaceAudience.LimitedPrivate; -import org.apache.yetus.audience.InterfaceAudience.Private; -import org.apache.yetus.audience.InterfaceAudience.Public; - -/** - * Annotation to inform users of how much to rely on a particular package, - * class or method not changing over time. Currently the stability can be - * {@link Stable}, {@link Evolving} or {@link Unstable}. <br> - * - * <ul><li>All classes that are annotated with {@link Public} or - * {@link LimitedPrivate} must have InterfaceStability annotation. </li> - * <li>Classes that are {@link Private} are to be considered unstable unless - * a different InterfaceStability annotation states otherwise.</li> - * <li>Incompatible changes must not be made to classes marked as stable.</li> - * </ul> - */ [email protected] [email protected] -public class InterfaceStability { - /** - * Can evolve while retaining compatibility for minor release boundaries.; - * can break compatibility only at major release (ie. at m.0). - */ - @Documented - @Retention(RetentionPolicy.RUNTIME) - public @interface Stable {}; - - /** - * Evolving, but can break compatibility at minor release (i.e. m.x) - */ - @Documented - @Retention(RetentionPolicy.RUNTIME) - public @interface Evolving {}; - - /** - * No guarantee is provided as to reliability or stability across any - * level of release granularity. - */ - @Documented - @Retention(RetentionPolicy.RUNTIME) - public @interface Unstable {}; -} http://git-wip-us.apache.org/repos/asf/yetus/blob/35718141/audience-annotations/src/main/java/org/apache/yetus/audience/tools/ExcludePrivateAnnotationsJDiffDoclet.java ---------------------------------------------------------------------- diff --git a/audience-annotations/src/main/java/org/apache/yetus/audience/tools/ExcludePrivateAnnotationsJDiffDoclet.java b/audience-annotations/src/main/java/org/apache/yetus/audience/tools/ExcludePrivateAnnotationsJDiffDoclet.java deleted file mode 100644 index 9ad94ab..0000000 --- a/audience-annotations/src/main/java/org/apache/yetus/audience/tools/ExcludePrivateAnnotationsJDiffDoclet.java +++ /dev/null @@ -1,64 +0,0 @@ -/* - * 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.yetus.audience.tools; - -import com.sun.javadoc.DocErrorReporter; -import com.sun.javadoc.LanguageVersion; -import com.sun.javadoc.RootDoc; - -import jdiff.JDiff; - -import org.apache.yetus.audience.InterfaceAudience; -import org.apache.yetus.audience.InterfaceStability; - -/** - * A <a href="http://java.sun.com/javase/6/docs/jdk/api/javadoc/doclet/";>Doclet</a> - * for excluding elements that are annotated with - * {@link org.apache.yetus.audience.InterfaceAudience.Private} or - * {@link org.apache.yetus.audience.InterfaceAudience.LimitedPrivate}. - * It delegates to the JDiff Doclet, and takes the same options. - */ [email protected] [email protected] -public class ExcludePrivateAnnotationsJDiffDoclet { - - public static LanguageVersion languageVersion() { - return LanguageVersion.JAVA_1_5; - } - - public static boolean start(RootDoc root) { - System.out.println( - ExcludePrivateAnnotationsJDiffDoclet.class.getSimpleName()); - return JDiff.start(RootDocProcessor.process(root)); - } - - public static int optionLength(String option) { - Integer length = StabilityOptions.optionLength(option); - if (length != null) { - return length; - } - return JDiff.optionLength(option); - } - - public static boolean validOptions(String[][] options, - DocErrorReporter reporter) { - StabilityOptions.validOptions(options, reporter); - String[][] filteredOptions = StabilityOptions.filterOptions(options); - return JDiff.validOptions(filteredOptions, reporter); - } -} http://git-wip-us.apache.org/repos/asf/yetus/blob/35718141/audience-annotations/src/main/java/org/apache/yetus/audience/tools/ExcludePrivateAnnotationsStandardDoclet.java ---------------------------------------------------------------------- diff --git a/audience-annotations/src/main/java/org/apache/yetus/audience/tools/ExcludePrivateAnnotationsStandardDoclet.java b/audience-annotations/src/main/java/org/apache/yetus/audience/tools/ExcludePrivateAnnotationsStandardDoclet.java deleted file mode 100644 index a0eb8b6..0000000 --- a/audience-annotations/src/main/java/org/apache/yetus/audience/tools/ExcludePrivateAnnotationsStandardDoclet.java +++ /dev/null @@ -1,63 +0,0 @@ -/* - * 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.yetus.audience.tools; - -import com.sun.javadoc.DocErrorReporter; -import com.sun.javadoc.LanguageVersion; -import com.sun.javadoc.RootDoc; -import com.sun.tools.doclets.standard.Standard; - -import org.apache.yetus.audience.InterfaceAudience; -import org.apache.yetus.audience.InterfaceStability; - -/** - * A <a href="http://java.sun.com/javase/6/docs/jdk/api/javadoc/doclet/";>Doclet</a> - * for excluding elements that are annotated with - * {@link org.apache.yetus.audience.InterfaceAudience.Private} or - * {@link org.apache.yetus.audience.InterfaceAudience.LimitedPrivate}. - * It delegates to the Standard Doclet, and takes the same options. - */ [email protected] [email protected] -public class ExcludePrivateAnnotationsStandardDoclet { - - public static LanguageVersion languageVersion() { - return LanguageVersion.JAVA_1_5; - } - - public static boolean start(RootDoc root) { - System.out.println( - ExcludePrivateAnnotationsStandardDoclet.class.getSimpleName()); - return Standard.start(RootDocProcessor.process(root)); - } - - public static int optionLength(String option) { - Integer length = StabilityOptions.optionLength(option); - if (length != null) { - return length; - } - return Standard.optionLength(option); - } - - public static boolean validOptions(String[][] options, - DocErrorReporter reporter) { - StabilityOptions.validOptions(options, reporter); - String[][] filteredOptions = StabilityOptions.filterOptions(options); - return Standard.validOptions(filteredOptions, reporter); - } -} http://git-wip-us.apache.org/repos/asf/yetus/blob/35718141/audience-annotations/src/main/java/org/apache/yetus/audience/tools/IncludePublicAnnotationsStandardDoclet.java ---------------------------------------------------------------------- diff --git a/audience-annotations/src/main/java/org/apache/yetus/audience/tools/IncludePublicAnnotationsStandardDoclet.java b/audience-annotations/src/main/java/org/apache/yetus/audience/tools/IncludePublicAnnotationsStandardDoclet.java deleted file mode 100644 index ee6afd2..0000000 --- a/audience-annotations/src/main/java/org/apache/yetus/audience/tools/IncludePublicAnnotationsStandardDoclet.java +++ /dev/null @@ -1,68 +0,0 @@ -/* - * 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.yetus.audience.tools; - -import com.sun.javadoc.DocErrorReporter; -import com.sun.javadoc.LanguageVersion; -import com.sun.javadoc.RootDoc; -import com.sun.tools.doclets.standard.Standard; - -import org.apache.yetus.audience.InterfaceAudience; -import org.apache.yetus.audience.InterfaceStability; - -/** - * A <a href="http://java.sun.com/javase/6/docs/jdk/api/javadoc/doclet/";>Doclet</a> - * that only includes class-level elements that are annotated with - * {@link org.apache.yetus.audience.InterfaceAudience.Public}. - * Class-level elements with no annotation are excluded. - * In addition, all elements that are annotated with - * {@link org.apache.yetus.audience.InterfaceAudience.Private} or - * {@link org.apache.yetus.audience.InterfaceAudience.LimitedPrivate} - * are also excluded. - * It delegates to the Standard Doclet, and takes the same options. - */ [email protected] [email protected] -public class IncludePublicAnnotationsStandardDoclet { - - public static LanguageVersion languageVersion() { - return LanguageVersion.JAVA_1_5; - } - - public static boolean start(RootDoc root) { - System.out.println( - IncludePublicAnnotationsStandardDoclet.class.getSimpleName()); - RootDocProcessor.treatUnannotatedClassesAsPrivate = true; - return Standard.start(RootDocProcessor.process(root)); - } - - public static int optionLength(String option) { - Integer length = StabilityOptions.optionLength(option); - if (length != null) { - return length; - } - return Standard.optionLength(option); - } - - public static boolean validOptions(String[][] options, - DocErrorReporter reporter) { - StabilityOptions.validOptions(options, reporter); - String[][] filteredOptions = StabilityOptions.filterOptions(options); - return Standard.validOptions(filteredOptions, reporter); - } -} http://git-wip-us.apache.org/repos/asf/yetus/blob/35718141/audience-annotations/src/main/java/org/apache/yetus/audience/tools/RootDocProcessor.java ---------------------------------------------------------------------- diff --git a/audience-annotations/src/main/java/org/apache/yetus/audience/tools/RootDocProcessor.java b/audience-annotations/src/main/java/org/apache/yetus/audience/tools/RootDocProcessor.java deleted file mode 100644 index 46d7fac..0000000 --- a/audience-annotations/src/main/java/org/apache/yetus/audience/tools/RootDocProcessor.java +++ /dev/null @@ -1,247 +0,0 @@ -/* - * 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.yetus.audience.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.yetus.audience.InterfaceAudience; -import org.apache.yetus.audience.InterfaceStability; - -/** - * Process the {@link RootDoc} by substituting with (nested) proxy objects that - * exclude elements with Private or LimitedPrivate annotations. - * <p> - * 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<Object, Object> proxies = - new WeakHashMap<Object, Object>(); - - 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; - } - - @Override - 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<Object> list = new ArrayList<Object>(array.length); - for (Doc entry : array) { - if (!exclude(entry)) { - list.add(process(entry, componentType)); - } - } - return list.toArray((Object[]) Array.newInstance(componentType, list - .size())); - } - - private Object unwrap(Object proxy) { - if (proxy instanceof Proxy) - return ((ExcludeHandler) Proxy.getInvocationHandler(proxy)).target; - return proxy; - } - - private boolean isFiltered(Object[] args) { - return args != null && Boolean.TRUE.equals(args[0]); - } - - } - -} http://git-wip-us.apache.org/repos/asf/yetus/blob/35718141/audience-annotations/src/main/java/org/apache/yetus/audience/tools/StabilityOptions.java ---------------------------------------------------------------------- diff --git a/audience-annotations/src/main/java/org/apache/yetus/audience/tools/StabilityOptions.java b/audience-annotations/src/main/java/org/apache/yetus/audience/tools/StabilityOptions.java deleted file mode 100644 index d8f0bbf..0000000 --- a/audience-annotations/src/main/java/org/apache/yetus/audience/tools/StabilityOptions.java +++ /dev/null @@ -1,70 +0,0 @@ -/* - * 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.yetus.audience.tools; - -import com.sun.javadoc.DocErrorReporter; - -import java.util.ArrayList; -import java.util.List; -import java.util.Locale; - -class StabilityOptions { - public static final String STABLE_OPTION = "-stable"; - public static final String EVOLVING_OPTION = "-evolving"; - public static final String UNSTABLE_OPTION = "-unstable"; - - public static Integer optionLength(String option) { - String opt = option.toLowerCase(Locale.ENGLISH); - if (opt.equals(UNSTABLE_OPTION)) return 1; - if (opt.equals(EVOLVING_OPTION)) return 1; - if (opt.equals(STABLE_OPTION)) return 1; - return null; - } - - public static void validOptions(String[][] options, - DocErrorReporter reporter) { - for (int i = 0; i < options.length; i++) { - String opt = options[i][0].toLowerCase(Locale.ENGLISH); - if (opt.equals(UNSTABLE_OPTION)) { - RootDocProcessor.stability = UNSTABLE_OPTION; - } else if (opt.equals(EVOLVING_OPTION)) { - RootDocProcessor.stability = EVOLVING_OPTION; - } else if (opt.equals(STABLE_OPTION)) { - RootDocProcessor.stability = STABLE_OPTION; - } - } - } - - public static String[][] filterOptions(String[][] options) { - List<String[]> optionsList = new ArrayList<String[]>(); - for (int i = 0; i < options.length; i++) { - if (!options[i][0].equalsIgnoreCase(UNSTABLE_OPTION) - && !options[i][0].equalsIgnoreCase(EVOLVING_OPTION) - && !options[i][0].equalsIgnoreCase(STABLE_OPTION)) { - optionsList.add(options[i]); - } - } - String[][] filteredOptions = new String[optionsList.size()][]; - int i = 0; - for (String[] option : optionsList) { - filteredOptions[i++] = option; - } - return filteredOptions; - } - -} http://git-wip-us.apache.org/repos/asf/yetus/blob/35718141/audience-annotations/src/main/java/org/apache/yetus/audience/tools/package-info.java ---------------------------------------------------------------------- diff --git a/audience-annotations/src/main/java/org/apache/yetus/audience/tools/package-info.java b/audience-annotations/src/main/java/org/apache/yetus/audience/tools/package-info.java deleted file mode 100644 index 1ac8e49..0000000 --- a/audience-annotations/src/main/java/org/apache/yetus/audience/tools/package-info.java +++ /dev/null @@ -1,18 +0,0 @@ -/* - * 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.yetus.audience.tools;
