Apache
/
openjpa
mirror of https://github.com/apache/openjpa.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

OPENJPA-2030: Audit documentation 

git-svn-id: https://svn.apache.org/repos/asf/openjpa/trunk@1161350 13f79535-47bb-0310-9956-ffa450edef68
This commit is contained in:
Pinaki Poddar 2011-08-25 01:08:14 +00:00
parent 8996376462
commit 8daa92c745
1 changed files with 98 additions and 1 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

99
openjpa-project/src/doc/manual/ref_guide_logging.xml
View File

@ -19,7 +19,7 @@
-->
<chapter id="ref_guide_logging">
<title>
Logging
Logging and Auditing
</title>
<indexterm zone="ref_guide_logging">
<primary>
@ -605,4 +605,101 @@ and set its prefix to "LOG MSG", you would set the <literal>openjpa.Log
com.xyz.CustomLogFactory(Prefix="LOG MSG")
</programlisting>
</section>
<section id="ref_guide_audit">
<title>OpenJPA Audit</title>
Transactional applications often require to audit changes in persistent objects.
OpenJPA can enable audit facility for all persistent entities in few simple steps.
<section>
<title>Configuration</title>
<para><emphasis>Annotate Persistent Entity</emphasis>
Any persistence entity can be enabled for audit by annotating with
<literal>org.apache.openjpa.audit.Auditable</literal>.
</para>
<programlisting>
@javax.persistence.Entity
@org.apache.openjpa.audit.Auditable
public class MyDomainObject { ...}
</programlisting>
<para>
This <literal>Auditable</literal> annotation enables auditing of creation, update or delete of
<literal>MyDomainObject</literal> instances. The <literal>Auditable</literal> annotation accepts
list of enumerated values <literal>org.apache.openjpa.audit.AuditableOperation</literal> namely
<literal>CREATE</literal>, <literal>UPDATE</literal> and <literal>DELETE</literal> to customize
only appropriate operations be audited. By deafult, all of the above operations are audited.
</para>
<para><emphasis>Configure Persistence Configuration</emphasis>
The audit facility is invoked at runtime via configuration of <literal>META-INF/persistence.xml</literal>.
The following property configures auditing via a default auditor
</para>
<programlisting>&lt;property name="openjpa.Auditor" value="default"/&gt;</programlisting>
<para>
The default auditor does not do much. It simply prints each auditable instance with its latest and original
states on a standard console (or to a designated file).
</para>
<para>The <emphasis>latest</emphasis> state of an instance designates the state which is commited to the
database.
The <emphasis>original</emphasis>state designates the state when the instance entered the managed persistent
context. For example, when a new instance is persisted or a existing instance is loaded from the database.
</para>
</section>
<section>
<title>Developing custom auditing</title>
<para>
For real use case, an application will prefer more than printing the changed instances. The application, in
such case, needs to implement <literal>org.apache.openjpa.audit.Auditor</literal> interface.
This simple interface has the following method:
</para>
<programlisting>
/**
* OpenJPA runtime will invoke this method with the given parameters
* within a transaction.
*
* @param broker the active persistence context.
* @param newObjects the set of auditable objects being created. Can be empty, but never null.
* @param updates the set of auditable objects being updated. Can be empty, but never null.
* @param deletes the set of auditable objects being deleted. Can be empty, but never null.
*/
public void audit(Broker broker, Collection&lt;Audited> newObjects, Collection&lt;Audited> updates,
Collection&lt;Audited> deletes);
</programlisting>
<para>
OpenJPA runtime will invoke this method <emphasis>before</emphasis> database commit. Via this callback method,
the application receives
the auditable instances in three separate collections of <literal>org.apache.openjpa.audit.Auditable</literal>.
An <literal>Auditable</literal> instance provides the latest and original state of a persistent object.
The latest object is
the same persistent instance to be committed. The original instance is a transient instance holding the
original state of the instance when it entered the managed context. The active persistence context
is also supplied in this callback method, so that an application may decide to persist the audit log
in the same database.
</para>
<para>
It is important to note that the original object can not be persisted in the same transaction, because
it has the same persistent identity of the latest object.
</para>
<para>
A single instance of implemented <literal>org.apache.openjpa.audit.Auditor</literal> interface
is available for a persistence unit. However, an application's own implementation of this interface
need not be thread-safe, because OpenJPA runtime guards against concurrent invocation of the
callback method.
</para>
<para>
The <literal>org.apache.openjpa.audit.Auditor</literal> interface is configurable. Hence any bean style
getter and setter method on its implementation will be populated as usual for any other OpenJPA plugin.
In the following example,
</para>
<programlisting>
&lt;property name="openjpa.Auditor" value="com.acme.Auditor(param2=10,param2='hello')"/&gt;
</programlisting>
<para>
An instance of <literal>com.acme.Auditor</literal> will be instantiated and if it has been style getter and
setter methods for <literal>param1</literal> and <literal>param2</literal>, then the respective setters
will be called with <literal>10</literal> and <literal>"hello"</literal> before the instance being used.
</para>
</section>
</section>
</chapter>