1    package classUtils.pack.util; 
2     
3    import java.io.File; 
4     
5    /** 
6     * Classes implementing this interface can explore the classpath, retrieving the contents of Java 
7     * packages and enumerate the classes therein. 
8     * <p> 
9     * Multiple jars or directories containing different classes in the same package are supported. 
10    * <p> 
11    * However, different jars and directories containing the same class are not. 
12    *  
13    * @author Cristiano Sadun 
14    */ 
15   public interface ClassPackageExplorer { 
16        
17       /** 
18        * Status constant mask, indicating that a certain package is found in a directory.  
19        * @see #getStatus(java.lang.String) 
20        */ 
21       public static final int IN_DIRECTORY = 0; 
22        
23       /** 
24        * Status constant mask, indicating that a certain package is found in a jar file. 
25        * @see #getStatus(java.lang.String) 
26        */  
27       public static final int IN_JAR = 1; 
28        
29       /** 
30        * Status constant mask, indicating that a certain package is found in a jar file and is sealed. 
31        * @see #getStatus(java.lang.String) 
32        */  
33       public static final int IN_JAR_SEALED = 2; 
34    
35       /** 
36        * List the available packages. The classpath is scanned for classes, and each package is reported. 
37        * This can take a long time on first invocation. 
38        *  
39        * @return a list of package names 
40        */ 
41       public String [] listPackageNames(); 
42    
43       /** 
44        * List the available packages. The classpath is scanned for classes, and each package is reported. 
45        * <p> 
46        * This can take a long time on first invocation or if <tt>rescan</tt> is <b>true</b>. 
47        *  
48        * @param rescan forces a re-scanning 
49        * @return a list of package names 
50        */  
51       public String [] listPackageNames(boolean rescan); 
52        
53       /** 
54        * Return the names of the classes in the package. 
55        *  
56        * @param packageName the name of the package 
57        * @param a status bit mask (see status constant masks) indicating which files to list. 
58        * @return the names of the classes in the package. 
59        */ 
60       public String [] listPackage(String packageName, int status); 
61    
62       /** 
63        * Return the names of all the classes in the package. 
64        * This can take a long time on first invocation. 
65        * <p> 
66        * @param packageName the name of the package 
67        * @return the names of all the classes in the package. 
68        */  
69       public String [] listPackage(String packageName); 
70        
71       /** 
72        * Return information on whether the package lives in a directory, a jar file, a sealed jar 
73        * file or a combination. 
74        * <p> 
75        * This can take a long time on first invocation. 
76        *  
77        * @param packageName the name of the package 
78        * @return the distribution status for the given package, or -1 if the given package 
79        *          does not exist. 
80        */ 
81       public int getStatus(String packageName); 
82        
83       /** 
84        * Return the one or more files or directories where a package lives. 
85        * <p> 
86        * This can take a long time on first invocation. 
87        *  
88        * @param packageName the name of the package 
89        * @return the files containing classes belonging to the given package. 
90        */ 
91       public File[] getPackageFiles(String packageName); 
92        
93       /** 
94        * Return an error status for the explorer. 
95        *  
96        * @return <b>true</b> if an error has occurred while exploring the class path. 
97        */ 
98       public boolean hasErrorOccurred(); 
99        
100      /** 
101       * Return an error status for the explorer. 
102       */ 
103      public String getErrorLog(); 
104   
105  } 
106