|
While we always aim to release DataNucleus with as few bugs as possible, it is possible that during
the release cycle some issues will come up. Our release process uses more than 1000 unit tests aimed
at reproducing the majority of situations that users may come across, though clearly we can never
cover all situations with these tests. We also run the JDO2/JPA1 TCKs before each release to provide
extra checks to reduce the chance of regressions. The process for reporting issues is defined below :-
-
Check your input classes, MetaData and persistence code against the JDO/JPA spec and the
DataNucleus documentation. The majority of situations are errors in input relative to what
DataNucleus allows.
-
Search the DataNucleus Forum for a similar situation to see
if someone else has had the same issue and maybe resolved it.
-
Try the latest Nightly Build.
Things are usually fixed soon after being reported so the issue may no longer be an issue.
-
Search DataNucleus JIRA for an issue describing
your situation. If there is one then you can always check the status of the issue and post
against it in JIRA.
-
Start a thread on the DataNucleus Forum.
-
If there is nothing obvious incorrect in your situation and it happens in a released
version of DataNucleus then you can raise an issue in
DataNucleus JIRA.
You should then create a testcase and attach it to the JIRA issue (using "Attach File" on the
issue) - see below.
Bugs can only be raised against
released versions
of DataNucleus.
If you encounter
a bug that only appears in SVN trunk then you should either report it against a JIRA issue
related to that item in the current work-in-progress release, or otherwise report it to
developers. This is since something can hardly be a bug if it hasn't been released yet
This guide can also be used for providing testcases that demonstrate the need for new features.
A test case is needed to be able to reproduce possible issues. We require something that we
can simply take and run ourselves, using the following framework
-
Create a package "org.datanucleus.test"
-
Add the basic persistable classes to this package. Please give these simple names like A, B, C.
Calling your classes names that mean something in your language will likely mean nothing to us
and so we will not have much patience trying to understand them, hence using A, B, C etc
makes more sense.
-
Add the
package.jdo
to this package (if using annotations then you can omit this).
-
If your test case is to demonstrate a problem with DataNucleus SchemaTool or at runtime then
you need to provide a
datanucleus.properties
file containing the PMF properties required for
the datastore to demonstrate the issue
-
If your test case is to demonstrate a problem with DataNucleus at runtime (NOT the
DataNucleus Enhancer/DataNucleus SchemaTool) you then
need to
-
Write a
Main.java
and add to this package org.datanucleus.test - see below for an
example.
-
Mark in the
Main.java
which line causes the error.
-
Provide information about which version of which datastore should be used.
-
Your test case should be runnable with JDK 1.5
-
Your test case should impose no additional external dependencies.
-
Do not
add lines for "System.out". Instead use NucleusLogger messages. This means that
the messages appear in the log next to the DataNucleus logged messages. System.out is as
much use as a chocolate teapot in the debugging process
-
Your test case should have at most 4 or 5 classes. Anything more than this is unlikely to
get our attention without a prior Donation.
We do not have the time to analyse your application. Of course if you donate then we can
look at it.
-
A testcase SHOULD NOT INCLUDE jar files, build files, log4j.properties files or any
other such environment specific stuff. A testcase should be the order of 5Kb NOT 5Mb.
Any testcase submitted with such unnecessary contents will be rejected.
This testcase
format is the simplest possible and the least users should do is abide by the simplicity
and just provide what is needed
The above can then be put in a
zip
file and attached to the JIRA issue or Forum thread.
The zip file should look like this
. If it doesnt then you will likely be asked to repackage it.
Using something other than zip is likely to be non-portable (for example some Windows-specific "rar"
format which is totally useless for those of us who dont use Windows :-) )
datanucleus.properties
org/
org/datanucleus/
org/datanucleus/test/
org/datanucleus/test/MyClass1.java
org/datanucleus/test/MyClass2.java
org/datanucleus/test/Main.java
org/datanucleus/test/package.jdo
As an alternative to the above, and where you are familiar with JUnit and are willing to look
at the existing DataNucleus unit tests in SVN, then please create a JUnit test case that
utilises our existing suite of sample data etc.
If you provide a testcase in this way
your testcase should be a patch against current SVN trunk.
Again, this should be attached to the JIRA issue to which it relates.
By attaching a test case to DataNucleus JIRA, you hereby agree that it is contribution
to DataNucleus under the terms of the
Apache 2.0 License.
A template
datanucleus.properties
is shown below. Use this as a framework
javax.jdo.PersistenceManagerFactoryClass=org.datanucleus.jdo.JDOPersistenceManagerFactory
javax.jdo.option.ConnectionDriverName=com.mysql.jdbc.Driver
javax.jdo.option.ConnectionURL=jdbc:mysql://localhost/datanucleus
javax.jdo.option.ConnectionUserName=mysql
javax.jdo.option.ConnectionPassword=
datanucleus.autoCreateSchema=true
datanucleus.autoCreateColumns=true
A template
Main.java
for JDO is shown below. Use this as a framework
package org.datanucleus.test;
import java.util.Collection;
import java.util.List;
import java.util.Properties;
import java.util.Iterator;
import javax.jdo.JDOHelper;
import javax.jdo.PersistenceManager;
import javax.jdo.PersistenceManagerFactory;
import javax.jdo.Extent;
import javax.jdo.Query;
import javax.jdo.Transaction;
import org.datanucleus.util.NucleusLogger;
public class Main
{
static public void main(String[] args)
{
PersistenceManagerFactory pmf = JDOHelper.getPersistenceManagerFactory("datanucleus.properties");
// Persist some objects
PersistenceManager pm = pmf.getPersistenceManager();
Transaction tx = pm.currentTransaction();
try
{
tx.begin();
... (replace this with your code to persist your objects required to reproduce the problem)
MyClass myobj = new MyClass("name");
pm.makePersistent(myobj);
tx.commit();
}
catch (Exception e)
{
NucleusLogger.JDO.info(">> Exception thrown persisting objects : " + e.getMessage());
}
finally
{
if (tx.isActive())
{
tx.rollback();
}
}
// Perform some operation
tx = pm.currentTransaction();
try
{
tx.begin();
... (add your code here)
tx.commit();
}
catch (Exception e)
{
NucleusLogger.JDO.info(">> Exception thrown retrieving objects : " + e.getMessage());
}
finally
{
if (tx.isActive())
{
tx.rollback();
}
}
pm.close();
}
}
A template
Main.java
for JPA is shown below. Use this as a framework
package org.datanucleus.test;
import java.util.Collection;
import java.util.List;
import java.util.Properties;
import java.util.Iterator;
import javax.persistence.Persistence;
import javax.persistence.EntityManagerFactory;
import javax.persistence.EntityManager;
import javax.persistence.EntityTransaction;
import org.datanucleus.util.NucleusLogger;
public class Main
{
static public void main(String[] args)
{
EntityManagerFactory emf = Persistence.createEntityManagerFactory("Test", null);
EntityManager em = emf.createEntityManager();
EntityTransaction tx = em.getTransaction();
try
{
tx.begin();
... (replace this with your code to persist your objects required to reproduce the problem)
MyClass myobj = new MyClass("name");
em.persist(myobj);
tx.commit();
}
catch (Exception e)
{
NucleusLogger.JDO.info(">> Exception thrown persisting objects : " + e.getMessage());
}
finally
{
if (tx.isActive())
{
tx.rollback();
}
}
// Perform some operation
tx = em.getTransaction();
try
{
tx.begin();
... (add your code here)
tx.commit();
}
catch (Exception e)
{
NucleusLogger.JDO.info(">> Exception thrown retrieving objects : " + e.getMessage());
}
finally
{
if (tx.isActive())
{
tx.rollback();
}
em.close();
}
}
}
|
|