[hibernate-dev] Scanner contract

[Steve Ebersole]

On Sat 16 Mar 2013 03:29:22 AM CDT, Gunnar Morling wrote:
>
> interface ScanResult {
> public Set<String> getPackageNames();
> public Set<String> getClassNames();
> public Set<NamedInputStream> getResourceStreams();
> }
>
>
> Is there missing one method? Or is it 4 methods in the original design
> and one is not required with the new design?

The latter.  The current Scanner contract defined:

Set<NamedInputStream> getFilesInJar(URL jartoScan, Set<String> 
filePatterns);
Set<NamedInputStream> getFilesInClasspath(Set<String> filePatterns);

I consolidated this into one return group.


>
> The first thing to note is the move away from using
> java.lang.Class and
> java.lang.Package for returning the matching classes and packages.
> This
> facilitates the "late loading" of those on the classloader
> (jandex/classmate).
>
>
> Just a thought: would it make sense to return something like a
> ClassDescriptor or PackageDescriptor which would know how to
> materialize a given name into a Class or Package (by having methods
> such as asClass() etc.)? This might be helpful as it encapsulates
> which class loader to use and also avoids to accidentally use package
> names as class names etc.

I like that suggestion.  Not sure it makes sense have it encapsulate the 
link back to the classloader for loading.  But either way I definitely 
like the idea of the specific return type.


>
> ScanOptions essentially just allows us a way to pass in the things we
> want to limit on; search filters if you will.
>
>
> Is ScanOptions available somewhere already? Based on the name I assume
> this can contain several options. Would it alternatively make sense to
> have something like ScanOption... options?

The problem is that the different options apply to each "bucket" of 
returns.  So a simple list would certainly not work.  Now it is 
questionable whether the options are needed for the package and class 
name scanning.  The existing code essentially allows configurable set of 
annotations to limit the search:

Set<Package> getPackagesInJar(URL jartoScan, Set<Class<? extends 
Annotation>> annotationsToLookFor);
Set<Class<?>> getClassesInJar(URL jartoScan, Set<Class<? extends 
Annotation>> annotationsToLookFor);

but currently we always pass empty to getPackagesInJar and a static set 
of values to getClassesInJar.  So, to me it is questionable whether that 
is really needed.  The scanner could just do these since the code 
calling scanner never varies these.

Now, for getResourceStreams[1] if we drop the notion of any options for 
getPackageNames and getClassNames I can see the param being just a 
varargs/array of "scan option" objects.  But to me, this highlights the 
niceness of "parameter objects".  If we leave it as ScanOption and 
initially leave off options for getPackageNames and getClassNames but 
later decide to add it, the implementations of Scanner do not need to 
change.


[1] changing my mind to calling that getNamedInputStreams instead.