View source for Gemini/JPA/Documentation/Troubleshooting

== Troubleshooting ==

The following problems may exhibit themselves. Potential solutions are listed underneath each problem.

# ''EntityManagerFactory'' service does not appear to be registered
#* '''Possible Cause:''' The ''Meta-Persistence'' header is missing from the bundle manifest, or an improperly specified persistence descriptor path is listed.
#: '''Solution:''' Examine the ''Meta-Persistence'' manifest header and the persistence descriptor value entry to ensure all is correctly specified.
#* '''Possible Cause:''' The Gemini DBAccess bundle for the JDBC driver has not been started or has not had a chance to register a ''DataSourceFactory'' service for the driver before the persistence bundle was processed by Gemini JPA. 
#: '''Solution:''' Ensure the start order causes the DBAccess bundle to be started before the Gemini JPA bundle.
#* '''Possible Cause:''' The local JDBC driver packaged with the persistence bundle was not able to be found by Gemini JPA.
#: '''Solution:''' Ensure the JDBC driver is on the ''Bundle-ClassPath'' in the persistence bundle.
# "No persistence provider found... "
#* '''Possible Cause:''' The ''javax.persistence'' bundle was not fully activated before Gemini JPA processing began.
#: '''Solution:''' Ensure that the ''javax.persistence'' bundle has been activated and has had a chance to set the ProviderResolver to be the special OSGi resolver. If it does not have a chance to do it then the default resolver will be used and no provider will be found.

==== Debugging Options ====

The following system properties may be useful when problems occur. They can be specified using the –D runtime option as a java command line argument. No value is required; the existence of the property is enough to cause the debugging to occur.
<br><br>
{| border="1" cellspacing="0" cellpadding="5" align="center"
! Property Name
! Description
|- 
| org.eclipse.gemini.debug
| Prints out general trace statements of interest during debugging
|-
| org.eclipse.gemini.debug.weaving
| Prints out trace statements relating to weaving hooks
|-
| org.eclipse.gemini.debug.classloading
| Prints out trace statements relating to classloading
|-
| org.eclipse.gemini.debug.xml
| Prints out trace statements relating to persistence descriptor XML file parsing
|}
<br>
It is recommended that the ''org.eclipse.gemini.debug'' flag be enabled when asking for help with a problem or when submitting a trace to the forum.

Note: The following properties have been deprecated as of 1.2.0:
* GEMINI_DEBUG
* GEMINI_DEBUG_WEAVING
* GEMINI_DEBUG_CLASSLOADER
* GEMINI_DEBUG_XML

==== Internal Configuration ====

Some of the internal Gemini JPA persistence unit information is available to help with debugging. It can be accessed by invoking EntityManagerFactory.getProperties() and getting the Map<String,Object> associated with the "PUnitInfo" key. The following code example will return the internal configuration info for the persistence unit of the entity manager factory being invoked:

<source lang="java">
Map<String,Object> info = (Map<String,Object>) emf.getProperties().get("PUnitInfo");
</source>