[hibernate-dev] Scanner contract

Steve Ebersole steve at hibernate.org
Mon Mar 18 09:15:15 EDT 2013

On Mon 18 Mar 2013 05:14:01 AM CDT, Emmanuel Bernard wrote:
> JBoss AS does use this contract so if you break it, we will need some
> kind of compatibility matrix between Hibernate and JBoss AS and EAP.
> Not unsurmountable but always a small annoyance.
> Maybe other environments also make use of this interface but I am not
> aware of them.

As far as JBoss AS, Scott has been involved in this design from the 

> I'm surprised getUnqualifiedJarName is no longer needed. I thought we
> used it as the default PU name but the current code does not use 
> getUnqualifiedJarName
> anymore.

I have never seen that #getUnqualifiedJarName used aside from tests.

> We initially designed the Scanner interface to minimize the work the
> Scanner implementor has to do and keep as much of the JPA knowledge to
> HEM's code. Your design seems to require the Scanner to understand more of
> JPA including the notion of root jar and additional jar files.

There is actually very very very little "JPA knowledge" being asked of 
the Scanner in my proposal.  Keep in mind that in both the cases that 
have surfaced so far where we actually need "custom Scanner" both are 
cases where the Scanner provider is also the thing that is handing us 
the root/additional jars.  For EE JPA thats actually part of the 
PersistenceUnitInfo contract; no magic there.  So for JBoss AS (or 
another AS) to hand us both the PersistenceUnitInfo (with jar urls) and 
the Scanner (knowning how to scan said url protocols) is not 
unreasonable.  In the case of Enterprise OSGi (at least based on our 
initial target environment), we have a PersistenceUnitInfo that only 
points us to the root url (#getJarFileUrls returns nothing), but this is 
the kind of "environment specifics" the current implementation forces 
Hibernate to understand.  And then, in both cases it forces Hibernate to 
import and use non-standard APIs just to do the scanning (JBoss's 
VirtualFile contract and quite a few OSGi contracts).  The important 
point I think you are missing is that it is far more difficult asking 
Hibernate to understand all the url protocol schemes in play then for 
the environments using those protocols to tell use how to scan them.

> Things around:
> - getMappingFileNames to return the stream for these files,
Not at all following here.  Do you mean getMappingFileNames on the 
PersistenceUnitInfo?  Well that does *not* return streams, it returns 
Strings.  And the spec specifically says that the Strings are supposed 
to be the resource names of the mapping files (aka, they should be 
loadable by that name through ClassLoader).  So what exactly is the 
point here?

> - isExcludeUnlistedClasses to not scan classes in the root JAR,
Exactly.  This "option" only has bearing on the root jar.  For all other 
jars Hibernate tries to be friendly and load everything.  But, that is 
hardly "deep JPA knowledge".  The option in terms of the root jars maps 
directly to an explicit JPA discussion.  Nothing deep about the 
knowledge there.  And for the non-root jars, there is nothing JPA 
specific in this option; its purely a Hibernate *choice*.

> - getJarFileUrls
Again, I think you are missing the point that generally speaking the 
PersistenceUnitInfo provider and the Scanner provider are one-in-the-same.

> - look for META-INF/orm.xml in the root JAr (only) and exclude it if it
> is already listed explicitly in the getMappingFileNames to not process
> it twice.
Not sure how this is classified as "deep JPA knowledge".

> - getManagedClassNames depending on how much you delegate to the scanner
Again, not sure how this is classified as "deep JPA knowledge".  I 
assume you mean because of PUI#excludeUnlistedClasses, but see that 
discussion above.

> That makes me concerned about code duplication and bugs unless someone
> deep in JPA immplement all of these Scanner implementations.

So, I am really not seeing this "need for deep knowledge of JPA" on the 
Scanner implementor in what I propose.

More information about the hibernate-dev mailing list