[hibernate-dev] OGM: CheckStyle and imports due to JavaDoc comments

[Sanne Grinovero]

Let's relax this, the likelyhood of this introducing a real problem
affecting the runtime is extremely low, and there are better ways to
prevent that. I've reopened the issue.

Longer reasoning + better proposal:

 - we're arguing only about things used in javadoc but not code, this:
   -- makes the probability to trigger very small
   -- doesn't save us from screw ups anyway
 - IDEs don't help -> very annoying to find it out at pull request time
 - it is only a problem if you're loading an optional dependency which
shouln't be required for that specific component
   -- again restricts the application very much
   -- how likely is it that you're referencing a class which is so
much out of context to not be even a dependency of the current class?

Now to restrict these chances to zero - as I know some of us are more
perfectionists - I actually believe we should simply eradicate any
concept optional dependency. The whole concept, as defined by Maven,
is unreliable and tricky to handle. We could explore lots of better
ways, for example:
 # different Maven modules keeping the code dependency isolated to a
specific module
 # different source directories in the same M.Module to keep the
source unit isolated + check with checkstyle what is legal to be
imported with different rules on each path
 # checkstyle could also be setup to let you import a specific
external package only from a specific package

(example: make it illegal to import any org.jgroups.* stuff unless you
are in package org.hibernate.search.backends.impl.jgroups.* ) ..

I personally like the Maven module split better. I'd like to stress
that we usually have a 1:1 match between the Maven artifacts that we
produce during a release from modular source projects. This doesn't
have to be the case, I think we could output jar files which make
sense to a consumer which don't necessarily match 1:1 the source
structure.

What I'm getting to is that code blocks which use Apache Avro should
have their own isolated module, as the code which uses JGroups, or
those depending to JPA (optional, this one gets tricky..); but we
could (on a case by case) still wrap it all up in a single unit for
the consumer if we don't want to expose a fragmented project.

However we do that, the javadoc safety measure is so small that it's
almost pointless.
For the record however I'm pretty sure that some older JVMs would have
a problem with such a missing class definition, but I didn't say it
would actually load the class: that's a different phase of linkage, as
it needs to prevent circularity references.

Sanne

On 1 August 2013 09:36, Gunnar Morling <gunnar at hibernate.org> wrote:
> Does the concept of imports apply at runtime at all, or is this concept not
> only present at compile time, making life easier by allowing to refer to
> types using their simple name? In [1] it says about type names in class
> files:
>
> "Class and interface names that appear in class file structures are always
> represented in a fully qualified form known as binary names".
>
> I also can't see any part of the class file structure which would hold
> information about imports. So when an imported type is not used in the
> actual code, I don't think it will be referenced in the resulting class
> file and thus can't cause any issues when not being present.
>
> [1] http://docs.oracle.com/javase/specs/jvms/se7/html/jvms-4.html#jvms-4.2.1
>
>
>
> 2013/8/1 Emmanuel Bernard <emmanuel at hibernate.org>
>
>>
>> On 31 juil. 2013, at 13:14, Hardy Ferentschik wrote:
>>
>> >
>> > On 31 Jan 2013, at 10:41 AM, Gunnar Morling <gunnar at hibernate.org>
>> wrote:
>> >
>> >> Personally I prefer to include a class via fully qualified name if it
>> is only used in the javadocs.
>> >> I think the readability does not suffer too much and adding an actual
>> import has actually
>> >> runtime consequences. We already had cases where a javadoc import
>> caused a hard link
>> >> between code which is otherwise decoupled.
>> >>
>> >> WDYM exactly by "hard link" in this context? Is it about referencing a
>> type from an optional dependency which might not be present at runtime?
>> >
>> > Right, optional dependencies. Take JPA and Search. In the engine module
>> we avoid importing it directly and do processing of
>> > @Id reflectively. Having an import of javax.persitence.Id would create
>> a runtime dependency.
>> >
>> >> I just tried out this scenario (adding an import statement just for
>> JavaDoc to a type which is not present at runtime) and still could execute
>> the importing class
>> >> without problems. Only when accessing the imported type in the actual
>> code I'm getting a CNFE. But this might be specific to the VM in use, not
>> sure.
>> >
>> > We had this discussion now several times. I remember when we wrote this
>> reflection code the first time (many years back ;-))
>> > all referenced classes were eagerly loaded. In this case just having the
>> import statement required the class being
>> > available at runtime.  Obviously this must have changed a bit which also
>> is proven by your experiment.
>> >
>>
>> Of course my memory might be flawed but the problems I recall around
>> isolating a piece of code for hv, search and later bean validation from
>> core did not involve unused imports. Come to think of it, I have never seen
>> an *unused* import eagerly loading a class even though in practice it's
>> left unspecified by the JLS.
>>
>>
>>
> _______________________________________________
> hibernate-dev mailing list
> hibernate-dev at lists.jboss.org
> https://lists.jboss.org/mailman/listinfo/hibernate-dev