[hibernate-dev] Scanner contract

[Steve Ebersole]

I am proposing a change to the org.hibernate.jpa.packaging.spi.Scanner 
SPI.  First I suggest we make the scanning happen in one call, and that 
one call return a token of the result.  Currently we have 4 "scan" 
methods on the Scanner contract; I instead propose there be a ScanResult 
that holds those 4 results:

interface ScanResult {
     public Set<String> getPackageNames();
     public Set<String> getClassNames();
     public Set<NamedInputStream> getResourceStreams();
}

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).

To get a ScanResult, we'd call the newly consolidated method on Scanner:

interface Scanner {
     public ScanResult scan(PersistenceUnitDescriptor descriptor, 
ScanOptions options);
}

or maybe:

interface Scanner {
     public ScanResult scan(URL rootUrl, ScanOptions options);
}

though I definitely prefer the first option.

So the first thing to notice here is that there is one call to the 
scanner for the entire persistence unit, not the multiple calls we do 
today.  So the onus of scanning sub-jars and "other jars" moves to the 
Scanner.  This is helpful in OSGi environments.  It also allows easier 
caching on the Scanner impl side for deployment walking.  Lots of other 
little wins here IMO too.

ScanOptions essentially just allows us a way to pass in the things we 
want to limit on; search filters if you will.

I'd like to make this change in 4.3 (JPA 2.1 support), so please speak 
up sooner rather than later if you have disagree with this proposal.  
Comments, suggestions, improvements welcome.