| <html><head> |
| <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> |
| <title>8. OpenJPA Audit</title><base href="display"><link rel="stylesheet" type="text/css" href="css/docbook.css"><meta name="generator" content="DocBook XSL Stylesheets V1.79.1"><link rel="home" href="manual.html" title="Apache OpenJPA 3.0 User's Guide"><link rel="up" href="ref_guide_logging.html" title="Chapter 3. Logging and Auditing"><link rel="prev" href="ref_guide_logging_custom.html" title="7. Custom Log"><link rel="next" href="ref_guide_dbsetup.html" title="Chapter 4. JDBC"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">8. OpenJPA Audit</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="ref_guide_logging_custom.html">Prev</a> </td><th width="60%" align="center">Chapter 3. |
| Logging and Auditing |
| </th><td width="20%" align="right"> <a accesskey="n" href="ref_guide_dbsetup.html">Next</a></td></tr></table><hr></div><div class="section" id="ref_guide_audit"><div class="titlepage"><div><div><h2 class="title" style="clear: both">8. OpenJPA Audit</h2></div></div></div><div class="toc"><dl class="toc"><dt><span class="section"><a href="ref_guide_audit.html#d5e9423">8.1. Configuration</a></span></dt><dt><span class="section"><a href="ref_guide_audit.html#d5e9445">8.2. Developing custom auditing</a></span></dt></dl></div> |
| |
| Transactional applications often require to audit changes in persistent objects. |
| OpenJPA can enable audit facility for all persistent entities in few simple steps. |
| <div class="section" id="d5e9423"><div class="titlepage"><div><div><h3 class="title">8.1. Configuration</h3></div></div></div> |
| |
| <p><span class="emphasis"><em>Annotate Persistent Entity</em></span> |
| Any persistence entity can be enabled for audit by annotating with |
| <code class="literal">org.apache.openjpa.audit.Auditable</code>. |
| </p> |
| <pre class="programlisting"> |
| @javax.persistence.Entity |
| @org.apache.openjpa.audit.Auditable |
| public class MyDomainObject { ...} |
| </pre> |
| <p> |
| This <code class="literal">Auditable</code> annotation enables auditing of creation, update or delete of |
| <code class="literal">MyDomainObject</code> instances. The <code class="literal">Auditable</code> annotation accepts |
| list of enumerated values <code class="literal">org.apache.openjpa.audit.AuditableOperation</code> namely |
| <code class="literal">CREATE</code>, <code class="literal">UPDATE</code> and <code class="literal">DELETE</code> to customize |
| only appropriate operations be audited. By deafult, all of the above operations are audited. |
| </p> |
| <p><span class="emphasis"><em>Configure Persistence Configuration</em></span> |
| The audit facility is invoked at runtime via configuration of <code class="literal">META-INF/persistence.xml</code>. |
| The following property configures auditing via a default auditor |
| </p> |
| <pre class="programlisting"><property name="openjpa.Auditor" value="default"/></pre> |
| <p> |
| 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). |
| </p> |
| <p>The <span class="emphasis"><em>latest</em></span> state of an instance designates the state which is commited to the |
| database. |
| The <span class="emphasis"><em>original</em></span>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. |
| </p> |
| </div> |
| <div class="section" id="d5e9445"><div class="titlepage"><div><div><h3 class="title">8.2. Developing custom auditing</h3></div></div></div> |
| |
| |
| <p> |
| For real use case, an application will prefer more than printing the changed instances. The application, in |
| such case, needs to implement <code class="literal">org.apache.openjpa.audit.Auditor</code> interface. |
| This simple interface has the following method: |
| </p> |
| <pre class="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<Audited> newObjects, Collection<Audited> updates, |
| Collection<Audited> deletes); |
| </pre> |
| <p> |
| OpenJPA runtime will invoke this method <span class="emphasis"><em>before</em></span> database commit. Via this callback method, |
| the application receives |
| the auditable instances in three separate collections of <code class="literal">org.apache.openjpa.audit.Auditable</code>. |
| An <code class="literal">Auditable</code> 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. |
| </p> |
| <p> |
| 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. |
| </p> |
| <p> |
| A single instance of implemented <code class="literal">org.apache.openjpa.audit.Auditor</code> 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. |
| </p> |
| <p> |
| The <code class="literal">org.apache.openjpa.audit.Auditor</code> 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, |
| </p> |
| <pre class="programlisting"> |
| <property name="openjpa.Auditor" value="com.acme.Auditor(param2=10,param2='hello')"/> |
| </pre> |
| <p> |
| An instance of <code class="literal">com.acme.Auditor</code> will be instantiated and if it has been style getter and |
| setter methods for <code class="literal">param1</code> and <code class="literal">param2</code>, then the respective setters |
| will be called with <code class="literal">10</code> and <code class="literal">"hello"</code> before the instance being used. |
| </p> |
| </div> |
| |
| </div><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="ref_guide_logging_custom.html">Prev</a> </td><td width="20%" align="center"><a accesskey="u" href="ref_guide_logging.html">Up</a></td><td width="40%" align="right"> <a accesskey="n" href="ref_guide_dbsetup.html">Next</a></td></tr><tr><td width="40%" align="left" valign="top">7. |
| Custom Log |
| </td><td width="20%" align="center"><a accesskey="h" href="manual.html">Home</a></td><td width="40%" align="right" valign="top"> Chapter 4. |
| JDBC |
| </td></tr></table></div></body></html> |