What are reasons for eclipselink failing to autodetect entity classes?

I'm running eclipselink in an OSGi container and my entity classes are in their own bundle.

I have repeatedly run into the problem that Eclipselink fails to autodetect the entity classes, resulting in "Xyz is not a known entity type" messages. This is painful to debug and my somewhat helpless approach is to more or less randomly tweak configuration files until it works.

I wish I knew a more systematic approach, but I don't seem to know enough about possible reasons for the problem. What could they be? Is there an overview of what happens in autodetection and what is required for it to work?

So if you ran into the problem yourself and were able to determine one specific reason, post it here, or vote it up when you already see it. That way we could produce a list of typical issues sorted by frequency. I'll add the ones I actually solved.

Facts I know:

• eclipselink uses the OSGi extender pattern to listen for bundles registering and then sets them up
• it supposedly uses the class loader for the bundle that defines the persistence unit, if you're using 开发者_StackOverflow社区a persistence.xml for configuration, this is the bundle where that file should be located.

The eclipselink jpa is not able to persist objects of classes that extend entity classes. Those extended classes should be entity classes by itself.

The bundle with the entity classes doesn't have the correct JPA-PersistenceUnits header in its manifest. This header is how eclipselink finds out that there is a persistence unit to be processed.

If listing your classes explictly makes it work, the wrong / missing header was not your problem.

The entity class is not listed explicitly in the configuration of the persistence unit and the persistence.xml (or whatever config mechanism you use) doesn't set the exclude-unlisted-classes parameter to false (depending on whether you run Java SE or EE, it may be true by default).

If it helps to list your classes explicitly, this may be your problem.