From f7f9e8fba62e981c2f7e63b9ce18199c97003fef Mon Sep 17 00:00:00 2001 From: Henri Sara Date: Wed, 30 Jun 2010 11:33:42 +0000 Subject: [PATCH] #4907 javadoc for ClassPathExplorer svn changeset:13973/svn branch:6.4 --- .../gwt/widgetsetutils/ClassPathExplorer.java | 125 ++++++++++++++++-- 1 file changed, 117 insertions(+), 8 deletions(-) diff --git a/src/com/vaadin/terminal/gwt/widgetsetutils/ClassPathExplorer.java b/src/com/vaadin/terminal/gwt/widgetsetutils/ClassPathExplorer.java index aa65d80d96..838b04f909 100644 --- a/src/com/vaadin/terminal/gwt/widgetsetutils/ClassPathExplorer.java +++ b/src/com/vaadin/terminal/gwt/widgetsetutils/ClassPathExplorer.java @@ -57,6 +57,9 @@ public class ClassPathExplorer { private static Logger logger = Logger .getLogger("com.vaadin.terminal.gwt.widgetsetutils"); + /** + * File filter that only accepts directories. + */ private final static FileFilter DIRECTORIES_ONLY = new FileFilter() { public boolean accept(File f) { if (f.exists() && f.isDirectory()) { @@ -67,14 +70,34 @@ public class ClassPathExplorer { } }; + /** + * Raw class path entries as given in the java class path string. Only + * entries that could include widgets/widgetsets are listed (primarily + * directories, Vaadin JARs and add-on JARs). + */ private static List rawClasspathEntries = getRawClasspathEntries(); + + /** + * Map from identifiers (either a package name preceded by the path and a + * slash, or a URL for a JAR file) to the corresponding URLs. This is + * constructed from the class path. + */ private static Map classpathLocations = getClasspathLocations(rawClasspathEntries); + /** + * No instantiation from outside, callable methods are static. + */ private ClassPathExplorer() { } /** - * Finds server side widgets with {@link ClientWidget} annotation. + * Finds server side widgets with {@link ClientWidget} annotation on the + * class path (entries that can contain widgets/widgetsets - see {@link #getRawClasspathEntries()}). + * + * As a side effect, also accept criteria are searched under the same class + * path entries and added into the acceptCriterion collection. + * + * @return a collection of {@link Paintable} classes */ public static Collection> getPaintablesHavingWidgetAnnotation() { @@ -87,6 +110,12 @@ public class ClassPathExplorer { } + /** + * Finds all accept criteria having client side counterparts (classes with + * the {@link ClientCriterion} annotation). + * + * @return Collection of AcceptCriterion classes + */ public static Collection> getCriterion() { if (acceptCriterion.isEmpty()) { // accept criterion are searched as a side effect, normally after @@ -97,9 +126,9 @@ public class ClassPathExplorer { } /** - * Finds available widgetset names. + * Finds the names and locations of widgetsets available on the class path. * - * @return + * @return map from widgetset classname to widgetset location URL */ public static Map getAvailableWidgetSets() { Map widgetsets = new HashMap(); @@ -120,6 +149,22 @@ public class ClassPathExplorer { return widgetsets; } + /** + * Finds all GWT modules / Vaadin widgetsets in a valid location. + * + * If the location is a directory, all GWT modules (files with the + * ".gwt.xml" extension) are added to widgetsets. + * + * If the location is a JAR file, the comma-separated values of the + * "Vaadin-Widgetsets" attribute in its manifest are added to widgetsets. + * + * @param locationString + * an entry in {@link #classpathLocations} + * @param widgetsets + * a map from widgetset name (including package, with dots as + * separators) to a URL (see {@link #classpathLocations}) - new + * entries are added to this map + */ private static void searchForWidgetSets(String locationString, Map widgetsets) { @@ -192,8 +237,12 @@ public class ClassPathExplorer { } /** - * Determine every URL location defined by the current classpath, and it's - * associated package name. + * Splits the current class path into entries, and filters them accepting + * directories, Vaadin add-on JARs with widgetsets and Vaadin JARs. + * + * Some other non-JAR entries may also be included in the result. + * + * @return filtered list of class path entries */ private final static List getRawClasspathEntries() { // try to keep the order of the classpath @@ -225,6 +274,13 @@ public class ClassPathExplorer { /** * Determine every URL location defined by the current classpath, and it's * associated package name. + * + * See {@link #classpathLocations} for information on output format. + * + * @param rawClasspathEntries + * raw class path entries as split from the Java class path + * string + * @return map of classpath locations, see {@link #classpathLocations} */ private final static Map getClasspathLocations( List rawClasspathEntries) { @@ -237,6 +293,22 @@ public class ClassPathExplorer { return locations; } + /** + * Checks a class path entry to see whether it can contain widgets and + * widgetsets. + * + * All directories are automatically accepted. JARs are accepted if they + * have the "Vaadin-Widgetsets" attribute in their manifest or the JAR file + * name contains "vaadin-" or ".vaadin.". + * + * Also other non-JAR entries may be accepted, the caller should be prepared + * to handle them. + * + * @param classpathEntry + * class path entry string as given in the Java class path + * @return true if the entry should be considered when looking for widgets + * or widgetsets + */ private static boolean acceptClassPathEntry(String classpathEntry) { if (!classpathEntry.endsWith(".jar")) { // accept all non jars (practically directories) @@ -279,7 +351,8 @@ public class ClassPathExplorer { } /** - * Recursively add subdirectories and jar files to classpathlocations + * Recursively add subdirectories and jar files to locations - see + * {@link #classpathLocations}. * * @param name * @param file @@ -325,6 +398,12 @@ public class ClassPathExplorer { } } + /** + * Add a jar file to locations - see {@link #classpathLocations}. + * + * @param name + * @param locations + */ private static void includeJar(File file, Map locations) { try { URL url = new URL("file:" + file.getCanonicalPath()); @@ -342,6 +421,18 @@ public class ClassPathExplorer { } + /** + * Searches for all paintable classes and accept criteria under a location + * based on {@link ClientWidget} and {@link ClientCriterion} annotations. + * + * Note that client criteria are updated directly to the + * {@link #acceptCriterion} field, whereas paintables are added to the + * paintables map given as a parameter. + * + * @param location + * @param locationString + * @param paintables + */ private final static void searchForPaintables(URL location, String locationString, Collection> paintables) { @@ -399,8 +490,12 @@ public class ClassPathExplorer { } - // Hide possible errors, exceptions from static initializers from - // classes we are inspecting + /** + * A print stream that ignores all output. + * + * This is used to hide error messages from static initializers of classes + * being inspected. + */ private static PrintStream devnull = new PrintStream(new OutputStream() { @Override public void write(int b) throws IOException { @@ -408,8 +503,22 @@ public class ClassPathExplorer { } }); + /** + * Collection of all {@link AcceptCriterion} classes, updated as a side + * effect of {@link #searchForPaintables(URL, String, Collection)} based on + * {@link ClientCriterion} annotations. + */ private static Set> acceptCriterion = new HashSet>(); + /** + * Checks a class for the {@link ClientWidget} and {@link ClientCriterion} + * annotations, and adds it to the appropriate collection if it has either. + * + * @param fullclassName + * @param paintables + * the collection to which to add server side classes with + * {@link ClientWidget} annotation + */ private static void tryToAdd(final String fullclassName, Collection> paintables) { try { -- 2.39.5