There's alot of overlap between the EJB3 and hibernate-extension annotations. For example, @Entity...

However, there doesn't seem to be a way to just use the hibernate extension annotations. (For example, if I want an @Entity with access = FIELD and mutable = true.) I think the majority of users will have to fall back on the Hibernate extensions, and it's much easier for a developer to keep track of one set of persistence annotation APIs rather than two...

We discussed this recently at our dev meeting and the conclusion was:

No, its a lot easier for developers to use only the standard extensions and when they have to, use an additional @org.hibernate.annotation.* (not globally imported). This keeps code maintainable and easily portable. You can immediately get an overview of what Hibernate-specific annotations you use by simply searching the source code for org.hibernate.annotations. The result of that search includes all code snippets. It also makes writing and reading examples a lot easier.

With all due respect, I don't buy the portability argument. EJB3 persistence as defined by the standards bodies will always be behind the curve as a complete solution, so all developers will have to fall back to Hibernate extensions (or some other ORM provider's extensions). So H3/Annotations will become the de facto standard as Hibernate 2.x is now. Maybe I'm short-sighted, but I don't see anyone else coming up with a free, reliable and widely used ORM solution.

I also don't see a case where a group starts developing with Hibernate, then decides to go with another ORM solution. It's hard to compete with free, stable and widely-used. Even in the unlikely scenario of an API switch, I doubt that coding to strict EJB3 persistence standards then using additional Hibernate annotations will help anyone make the switch. So instead of editing the @Entity annotation, you wind up deleting the @org.hibernate.annotations.Entity annotation and replacing it with a different one.

I guess my main objection is the lack of integrated EJB3+Hibernate Extensions documentation. Right now, one would basically have to read the (incomplete) JSR EJB3 doc, then the Hibernate EJB3 reference documentation, and then look at the API docs for both to figure out which function or feature can be called from where...

Then again, maybe this will all be moot when HiA 2 comes out :)

Those who have written applications with annotations will be able to tell you if its possible or not to use only EJB3 annotations. I don't think it is possible, from my experience, to write a real-world application without vendor annotations. However, I had to use them much less frequently than I thought I would have, and I can certainly imagine to replace them with annotations from another vendor. If you have worked with annotations for a while you'll realize that its not about one being older or less up-to-date than the other. EJB3 really defines the basic mapping features, which, for Hibernate at least, haven't changed at all in 4 years and are unlikely to be ever replaced with completely different annotations. The org.hibernate.annotations are actually real extensions, quite a few only relevant for performance optimization.

Yes, HiA SE will show all XML and annotation mappings side-by-side. All you need, by the way, is the excellent Hibernate Annotations reference documentation (thanks to Emmanuel) in addition to the Hibernate reference.