]> &api-questions;

This module provides the which allows the infrastructure supporting Java Persistence API (JPA) to retrieve informatiou about JPA features provided by projects. It mainly consists of SPI interfaces which must be implemented by projects and put in their default lookups.

All Javadoc-specified functionality should be covered by unit tests.

The implementation is done. The target milestone is promo-G.

The entry point to the Java Persistence API is the persistence.xml file, which contains persistence units. Persistence units are logical groupings of entity classes and mapping metadata which specifies the mapping of the entity classes to a database.

The support for Java Persistence API needs to locate the default location for the persistence.xml file in a project and to trigger the creation of this location if it doesn't exist. This is supported by the PersistenceLocation class. It delegates to the PersistenceLocationProvider interface, which is supposed to be implemented by projects and put in their lookups.

The entity classes defined by a persistence.xml file can be used by clients, e.g. a servlet or an EJB session bean. It must be possible for such as client to find out if there is a persistence.xml available and the entity classes defined by its persistence units.

For this the concept of a persistence scope was introduced. A persistence scope is the grouping of a persistence.xml file and a classpath containing entity classes. A persistence scope is described by the PersistenceScope class. The PersistenceScope.getPersistenceScope(FileObject) method can be used to retrieve the persistence scope for a given FileObject. This method delegates to the PersistenceScopeProvider, which must be implemented by projects and put in their lookups.

A PersistenceScope instance is created by implementing the PersistenceScopeImplementation interface and passing it to the PersistenceScopeFactory.createPersistenceScope() method.

Sometimes it is necessary to retrieve a list of all persistence scopes defined by a project and it must be possible to listen for changes to this list. This is supported by the PersistenceScopes class. The PersistenceScopes.getPersistenceScopes(Project) method can be used to retrieve a PersistenceScopes for a given project. This method delegates to the PersistenceScopesProvider, which mus be implemented by projects and put in their lookups.

The PersistenceScopes.getPersistenceScopes() method can be used to retrieve an array of PersistenceScope's. There are also methods for adding and removing a PropertyChangeListener for listening on the list of persistence scopes.

A PersistenceScopes instance is created by implementing the PersistenceScopesImplementation interface and passing it to the PersistenceScopesFactory.createPersistenceScopes() method.

To help a project implement PersistenceScopesProvider easily the PersistenceScopesHelper class is provided. It supports managing a PersistenceScope and listening to the respective persistence.xml file and sending property change events accordingly.

The support for Java Persistence API needs to retrieve the entity classes defined in a project. A project can serve as a class library containing entity classes for other projects which does not contain a persistence.xml itself, thus it doesn't provide any PersistenceScope's. This is solved by the PersistenceClassPathProvider inteface, which returns a classpath containing entity classes.

This module provides APIs needed by the infrastructure supporting Java Persistence API to locate the persistence features provided by projects.

The module does not contain any UI, so it does not need to be internationalized.

The module does not define nor implement any standards.

The module does not save nor read any settings.

The module requires JRE 1.4.

JRE is enough.

The module does not depend on any projects outside NetBeans.

The module should run in the samy way on all platforms.

Only friend modules can declare a dependency on this module.

Just the module JAR needs to be deployed.

Yes.

Only API packages are exported, and only to the friend modules.

Anywhere.

No.

The API is thread-safe. Events are fired synchronously.

None.

The module does not read or write any files.

Implementations of PersistenceScopeProvider are searched for in the default lookup and delegated to until one is found which returns a non-null value.

An implementation of the PersistenceScopeProvider interface delegating to the project which owns the FileObject passed to the findPersistenceScope() method is registered in the default lookup using META-INF/services.

No.

None known.

The implementation doesn't consume any memory apart from some static fields, e.g. the Lookup.Result containing the registered PersistenceScopeProvider's.

No.

Performance scales linearly with the number of registered clients.

The plugged-in code is expected to execute quickly.

No.