Hi,
I would like to thank Chris for managing the commits and writting very good
javadoc
for ContentInterceptors.
I've put it with an overview and Juergen recommandations into a howto here
attached.
UserQuotaContentInterceptor patches will follow this week.
Regards
jp
<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE document [
<!ENTITY project SYSTEM "stylesheets/project.xml">
]>
<document>
&project;
<properties>
<author email="[EMAIL PROTECTED]">Christopher Lenz</author>
<author email="[EMAIL PROTECTED]">Jean-Philippe Courson</author>
<title>ContentInterceptors Howto</title>
</properties>
<body>
<section name="Overview">
<p>
ContentInterceptors are a way to smoothly plug your own software logic
into slide.
</p>
<p>
They let you choose actions that you want to be performed on content
management events such as content add, update or remove.
</p>
</section>
<section name="How to write a ContentInterceptor ?">
<p>
To implement the <tt>org.apache.slide.content.ContentInterceptor</tt>
interface, you need to subclass
<tt>org.apache.slide.content.AbstractContentInterceptor</tt> class and
overwrite one or more of its methods depending on the type of event you
want to intercept :
<ul>
<li>preStoreContent</li>
<li>postStoreContent</li>
<li>preRemoveContent</li>
<li>postRemoveContent</li>
<li>preRetrieveContent</li>
<li>postRetrieveContent</li>
</ul>
See <a href="javadoc/org/apache/slide/content/AbstractContentInterceptor.html">JavaDoc</a>
for complete methods prototype.
</p>
<p>
<code>ContentInterceptor</code> implementations must also provide a
public constructor without arguments, so that instances of the class can be
instantiated at startup.
</p>
<p>
In addition, implementors should pay attention to this minimal lifecycle definition:
<ul>
<li>When the namespace is being configured, <code>setParameters</code>
will be called with a <code>java.util.Hashtable</code> containing the
parameter names and values as specified in the configuration.</li>
<li>When configuration is completed, <code>setNamespace</code> will be
called, passing in a <code>NamespaceAccessToken</code> than can later
be used by the <code>ContentInterceptor</code> to perform its deeds
(like logging to the namespace logger).</li>
<li>After that, any of the <code>preXXX</code> and <code>postXXX</code>
methods will be called as soon as the associated event occurs.</li>
</ul>
</p>
</section>
<section name="Plug your ContentInterceptor into slide">
<p>
Multiple <code>ContentInterceptors</code> can be associated with a single
<code>Namespace</code>. They are typically configured in the
<code><configuration></code> section of the domain configuration
file like this:
</p>
<p><code>
 <content-interceptor class="com.acme.MyContentInterceptor">
<br/>
  <parameter name="myParam1">someValue</parameter>
<br/>
  <parameter name="myParam2">anotherValue</parameter>
<br/>
 </content-interceptor>
</code></p>
<p>
As you can see, <code>ContentInterceptors</code> can be configured with
parameters. This is optional, and exactly which parameters are available
depends on the specific <code>ContentInterceptor</code> implementation.
</p>
</section>
<section name="Warnings">
<subsection name="Exceptions">
<p>
The signatures of the <code>preXXX</code> and <code>postXXX</code> specify
a wide range of exceptions that can be thrown. If such an exception is
thrown it will be propagated up to the the API client.
</p>
<p>
In the case of the <code>preXXX</code> the started operation will be
terminated. So be sure to handle all exceptions that shouldn't be
propagated back into the core core API - and thus possibly influence
success of the operation - yourself.
</p>
</subsection>
<subsection name="Servlet filters vs ContentInterceptors">
<p>
When using a servlet container that implements Servlet 2.3 specifications,
you can use Servlet filters that might be sufficient for you application.
</p>
</subsection>
</section>
<section name="Samples">
<p>
<code>UserQuotaContentInterceptor</code> class may be used as an example.
</p>
<p>
See <a href="javadoc/org/apache/slide/content/UserQuotaContentInterceptor.html">JavaDoc</a>
for more informations.
</p>
</section>
</body>
</document>
--
To unsubscribe, e-mail: <mailto:[EMAIL PROTECTED]>
For additional commands, e-mail: <mailto:[EMAIL PROTECTED]>
