[hibernate-dev] Removal of Hibernate Commons Annotations from Hibernate Search -> middle-ground solution?

[Gunnar Morling]

I don't have a completely satisfying answer to this question, but an ad-hoc
solution which may work well enough.

The idea is to use SigTest [1] to create a file which contains all the
signatures of your public API; This file contains information about method
parameter and return types but also inheritance relationships so you find
out whether any of your API types extends a type from Hibernate Commons
Annotations. This signature file does not contain information about
non-exposed references (if private methods or if an API method references a
type from HCA via a local variable which should be allowed for your
purposes). You also can exclude internal packages from the file altogether.
Any reference to types from HCA in that signature file are then a place
where you leak HCA through to users.

As an experiment, I ran the tool on the engine module and found the
following references to HCA types from what I think are members of your
public API/SPI:

* org.hibernate.search.cfg.spi.SearchConfiguration#getReflectionManager()
* org.hibernate.search.engine.spi.AbstractDocumentBuilder#<init>
* org.hibernate.search.engine.spi.AbstractDocumentBuilder#getBeanXClass()
* org.hibernate.search.engine.spi.DocumentBuilderContainedEntity#<init>
* org.hibernate.search.engine.spi.DocumentBuilderIndexedEntity#<init>
*
org.hibernate.search.engine.spi.DocumentBuilderContainedEntity#getIdGetter()
* org.hibernate.search.exception.AssertionFailure extends
org.hibernate.annotations.common.AssertionFailure

I ran the tool like this:

    export CLASSPATH=... # e.g. via mvn dependency:build-classpath -pl
engine -DincludeScope=compile

    java -jar ~/tools/sigtest-3.0/lib/sigtestdev.jar Setup -classpath
$JAVA_HOME/jre/lib/rt.jar:engine/target/hibernate-search-engine-5.0.0-SNAPSHOT.jar:/$CLASSPATH
-static -package org.hibernate.search -exclude
org.hibernate.search.query.dsl.impl -exclude
org.hibernate.search.engine.metadata.impl -exclude
org.hibernate.search.impl -exclude org.hibernate.search.util.logging.impl
-exclude org.hibernate.search.util.impl -exclude
org.hibernate.search.indexes.impl -exclude org.hibernate.search.bridge.impl
-exclude org.hibernate.search.engine.impl -NonClosedFile -FileName
search-deps.sig

package/exclude specify the API types of interest; NonClosedFile causes
only members from the specified search package to be included in the
created file. You can then grep search-deps.sig for references to HCA types.

Hth,

--Gunnar

[1] https://wiki.openjdk.java.net/display/CodeTools/SigTest




2014-06-23 21:53 GMT+02:00 Sanne Grinovero <sanne at hibernate.org>:

> This has been proposed several times, it's time to try converging on a
> stable API for Hibernate Search 5, and I have the idea that actual
> plans to remove the dependency are not mature.
>
> I would then propose to re-purpose HSEARCH-1213 to not fully remove
> hibernate-commons-annotations but to use it as an implementation
> detail only: make sure we hide it from user API, so to allow us to
> remove it later when possibly Hibernate ORM will be aligned on these
> plans too.
>
> Any suggestion on how we could verify this is done correctly?
> I thought of using checkstyle to consider it a violation to import
> HANN classes in the tests, but that's probably not solid enough - and
> some tests might need exceptions to the rule.
>
> Sanne
> _______________________________________________
> hibernate-dev mailing list
> hibernate-dev at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/hibernate-dev
>