You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@isis.apache.org by bu...@apache.org on 2014/03/04 09:14:40 UTC
svn commit: r899958 - in /websites/staging/isis/trunk: cgi-bin/ content/
content/reference/services/auditing-service.html
content/reference/services/command-context.html
Author: buildbot
Date: Tue Mar 4 08:14:39 2014
New Revision: 899958
Log:
Staging update by buildbot for isis
Modified:
websites/staging/isis/trunk/cgi-bin/ (props changed)
websites/staging/isis/trunk/content/ (props changed)
websites/staging/isis/trunk/content/reference/services/auditing-service.html
websites/staging/isis/trunk/content/reference/services/command-context.html
Propchange: websites/staging/isis/trunk/cgi-bin/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Tue Mar 4 08:14:39 2014
@@ -1 +1 @@
-1573747
+1573925
Propchange: websites/staging/isis/trunk/content/
------------------------------------------------------------------------------
--- cms:source-revision (original)
+++ cms:source-revision Tue Mar 4 08:14:39 2014
@@ -1 +1 @@
-1573747
+1573925
Modified: websites/staging/isis/trunk/content/reference/services/auditing-service.html
==============================================================================
--- websites/staging/isis/trunk/content/reference/services/auditing-service.html (original)
+++ websites/staging/isis/trunk/content/reference/services/auditing-service.html Tue Mar 4 08:14:39 2014
@@ -313,7 +313,7 @@
<p>The auditing service provides a simple mechanism to capture changes to data. It is called for each property that has changed on any domain object, as a set of pre- and post-values.</p>
-<h3>API [1.4.0-SNAPSHOT]</h3>
+<h2>API [1.4.0-SNAPSHOT]</h2>
<p>The API for the service is:</p>
@@ -332,7 +332,7 @@
<p><strong>BREAKING CHANGE!!!</strong> The previous APIs for this service (<code>AuditingService</code> and <code>AuditingService2</code>) have been removed. The new API is a superset of these previous APIs. The change was made so that the auditing service would be consistent with the related <a href="./publishing-service.html">Publishing</a> and the <a href="./command-context.html">Command Context</a> services.</p>
</blockquote>
-<h3>API [1.3.0]</h3>
+<h2>API [1.3.0]</h2>
<p>The API for the service is:</p>
@@ -351,7 +351,7 @@
<p>Note that the original API for this service was called <code>AuditingService</code>. This original API has been deprecated because it accidentally omitted the <code>propertyId</code> parameter.</p>
</blockquote>
-<h3>Implementations</h3>
+<h2>Implementations</h2>
<p>A simple implementation of the service that writes to stderr, is available, useful for debugging:</p>
@@ -362,7 +362,37 @@
<p>An alternative implementation, that persists audit records to a database, is the <a href="../../components/objectstores/jdo/services/publishing-service-jdo.html">JDO Publishing Service</a>. This implementation is only supported when the the <a href="../../components/objectstores/jdo/about.html">JDO objectstore</a> is configured.</p>
-<h3>Register the Service</h3>
+<h2>Usage</h2>
+
+<p>The typical way to indicate that an object should be audited is to annotate it with the <a href="../recognized-annotations/Audited.html">@Audited</a> annotation, for example:</p>
+
+<pre><code>@Audited
+public class ToDoItem ... {
+ ...
+}
+</code></pre>
+
+<p>As an alternative to annotating every object with <code>@Auditing</code>, alternatively this can be configured as the default. </p>
+
+<p>To treat every object as audited, add the following to <code>isis.properties</code>:</p>
+
+<pre><code>isis.services.audit.objects=all
+</code></pre>
+
+<p>To prevent an object from being audited (even if globally enabled), use the <code>@Audited</code> annotation with the <code>disabled</code> attribute:</p>
+
+<pre><code>@Audited(disabled=true)
+public class NotAuditedObject { ... }
+</code></pre>
+
+<p>To disable globally, use: </p>
+
+<pre><code>isis.services.audit.objects=none
+</code></pre>
+
+<p>If the key is not present in <code>isis.properties</code>, then objects are not audited by default.</p>
+
+<h2>Register the Service</h2>
<p>Register like any other service in <code>isis.properties</code>. For example, if using the <a href="../../components/objectstores/jdo/services/auditing-service-jdo.html">JDO auditing implementation</a> then it would be:</p>
Modified: websites/staging/isis/trunk/content/reference/services/command-context.html
==============================================================================
--- websites/staging/isis/trunk/content/reference/services/command-context.html (original)
+++ websites/staging/isis/trunk/content/reference/services/command-context.html Tue Mar 4 08:14:39 2014
@@ -314,20 +314,20 @@
<p>The <code>CommandContext</code> service is a <a href="../../more-advanced-topics/how-to-09-020-How-to-write-a-typical-domain-service.html">request-scoped</a> service that reifies the invocation of an action on a domain object into an object itself. This reified information is encapsulated within the <code>Command</code> object.</p>
<p>By default, the <code>Command</code> is held in-memory only; once the action invocation has completed, the <code>Command</code> object is gone. The optional
- supporting <code>CommandService</code> enables the implementation of <code>Command</code> to be pluggable, however, enabling the <code>Command</code> to be persisted.</p>
+ supporting <code>CommandService</code> enables the implementation of <code>Command</code> to be pluggable. With an appropriate implementation (eg the JDO implementation, described below) the <code>Command</code> may then be persisted.</p>
<p>Persistent <code>Command</code>s support several use cases:</p>
<ul>
<li>they enable profiling of the running application (which actions are invoked then most often, what is their response time)</li>
<li>they act as a parent to any background commands that might be invoked through the <a href="./background-service.html">BackgroundService</a></li>
-<li>if <a href="./auditing-service.html">auditing</a> is configured, they provide better audit information as the <code>Command</code> (the 'cause' of an action) can be correlated to the audit records (the "effect" of the action) through the unique <code>transactionId</code> GUID</li>
+<li>if <a href="./auditing-service.html">auditing</a> is configured, they provide better audit informatio, since the <code>Command</code> (the 'cause' of an action) can be correlated to the audit records (the "effect" of the action) through the unique <code>transactionId</code> GUID</li>
<li>if <a href="./publishing-service.html">publishing</a> is configured, they provide better traceability as the <code>Command</code> is also correlated with any published events, again through the unique <code>transactionId</code> GUID</li>
</ul>
<p>Assuming that the <code>CommandService</code> supports persistent <code>Command</code>s, the associated <a href="../recognized-annotations/Command.html">@Command</a> annotation also allows action invocations to be performed in the background. In this case the act of invoking the action on an object instead returns the <code>Command</code> to the user.</p>
-<h3>API</h3>
+<h2>API</h2>
<p>The <code>CommandContext</code> request-scoped service defines the following very simple API:</p>
@@ -390,7 +390,9 @@ public class CommandContext {
<li><code>getException()</code> - exception stack trace if action threw exception</li>
</ul>
-<h3>Implementation</h3>
+<h2>Implementation</h2>
+
+<h4>CommandContext</h4>
<p>The <code>CommandContext</code> implementation is part of the core framework (isis-core), in fact is a concrete class in the applib:</p>
@@ -398,6 +400,8 @@ public class CommandContext {
<li><code>org.apache.isis.applib.services.command.CommandContext</code></li>
</ul>
+<h4>CommandService (for persistent <code>Command</code>s)</h4>
+
<p>The <code>CommandService</code> interface - which acts as the factory for different <code>Command</code> implementations - is pluggable. Currently there is only a single implementation, provided by the JDO objectstore, which persists <code>Command</code>s to an RDBMS:</p>
<ul>
@@ -410,7 +414,62 @@ public class CommandContext {
<li><code>org.apache.isis.objectstore.jdo.applib.service.command.CommandServiceJdoRepository</code></li>
</ul>
-<h3>Usage</h3>
+<h2>Usage</h2>
+
+<h4>Explicitly treating an action as a command</h4>
+
+<p>The typical way to indicate that an action should be treated as a command is to annotate it with the <a href="../recognized-annotations/Command.html">@Command</a> annotation, for example:</p>
+
+<pre><code>public class ToDoItem ... {
+
+ @Command
+ public ToDoItem completed() { ... }
+
+}
+</code></pre>
+
+<p>The annotation can also be used to specify whether the command should be performed in the background, for example:</p>
+
+<pre><code>public class ToDoItem ... {
+
+ @Command(executeIn=ExecuteIn.BACKGROUND)
+ public ToDoItem scheduleImplicitly() {
+ completeSlowly(3000);
+ return this;
+ }
+}
+</code></pre>
+
+<p>When a background command is invoked, the user is returned the command object itself (to provide a handle to the command being invoked).</p>
+
+<h4>Making commands the default</h4>
+
+<p>As an alternative to annotating every action with <code>@Command</code>, alternatively this can be configured as the default. </p>
+
+<p>To treat every action as a command, add the following to <code>isis.properties</code>:</p>
+
+<pre><code>isis.services.command.actions=all
+</code></pre>
+
+<p>To treat only non-query actions as commands (ie those annotated with <a href="../recognized-annotations/ActionSemantics.html">@ActionSemantics</a> of IDEMPOTENT or NON_IDEMPOTENT), use:</p>
+
+<pre><code>isis.services.command.actions=ignoreQueryOnly
+</code></pre>
+
+<p>To prevent an action from being treated as a command (even if globally enabled), use the <code>@Command</code> annotation with the <code>disabled</code> attribute:</p>
+
+<pre><code>@Command(disabled=true)
+public void notACommand() { ... }
+</code></pre>
+
+<p>To disable globally, use: </p>
+
+<pre><code>isis.services.command.actions=none
+</code></pre>
+
+<p>If the key is not present in <code>isis.properties</code>, then commands are disabled by default.</p>
+
+<h4>Interating with the services</h4>
<p>Typically the domain objects have little need to interact with the <code>CommandContext</code> and <code>Command</code> directly; what is more useful is that these are persisted in support of the various use cases identified above.</p>
@@ -433,7 +492,7 @@ public class CommandContext {
<pre><code>String user = commandContext.getCommand().getUser();
</code></pre>
-<h3>Registering the Services</h3>
+<h2>Registering the Services</h2>
<p>Register like any other service in <code>isis.properties</code>. For example, if using the core <code>CommandContext</code> service along with the <a href="../../components/objectstores/jdo/services/command-service-jdo.html">JDO implementation</a> of the <code>CommandService</code>, then it would be:</p>
@@ -444,7 +503,7 @@ public class CommandContext {
...
</code></pre>
-<h3>Related Services</h3>
+<h2>Related Services</h2>
<p>These services are most often used in conjunction with the <code>BackgroundService</code> and <code>BackgroundCommandService</code> (both described <a href="./background-service.html">here</a>). For <code>BackgroundService</code> captures commands for execution in the background, while the [BackgroundCommandService] persists such commands for execution. </p>