| <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-NS Stylesheets V1.76.1"><link rel="home" href="manual.html" title="Apache OpenJPA 2.4 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" title="8. OpenJPA Audit"><div class="titlepage"><div><div><h2 class="title" style="clear: both" id="ref_guide_audit">8. OpenJPA Audit</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="ref_guide_audit.html#d5e9395">8.1. Configuration</a></span></dt><dt><span class="section"><a href="ref_guide_audit.html#d5e9417">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" title="8.1. Configuration"><div class="titlepage"><div><div><h3 class="title" id="d5e9395">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" title="8.2. Developing custom auditing"><div class="titlepage"><div><div><h3 class="title" id="d5e9417">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> |