ContentInterceptor


1   /*
2    * $Header: /home/cvs/jakarta-slide/src/share/org/apache/slide/content/ContentInterceptor.java,v 1.8 2004/07/28 09:37:56 ib Exp $
3    * $Revision: 1.8 $
4    * $Date: 2004/07/28 09:37:56 $
5    *
6    * ====================================================================
7    *
8    * Copyright 1999-2002 The Apache Software Foundation 
9    *
10   * Licensed under the Apache License, Version 2.0 (the "License");
11   * you may not use this file except in compliance with the License.
12   * You may obtain a copy of the License at
13   *
14   *     http://www.apache.org/licenses/LICENSE-2.0
15   *
16   * Unless required by applicable law or agreed to in writing, software
17   * distributed under the License is distributed on an "AS IS" BASIS,
18   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
19   * See the License for the specific language governing permissions and
20   * limitations under the License.
21   *
22   */ 
23  
24  package org.apache.slide.content;
25  
26  import java.util.Hashtable  ;
27  import org.apache.slide.common.NamespaceAccessToken;
28  import org.apache.slide.common.SlideToken;
29  import org.apache.slide.common.ServiceAccessException;
30  import org.apache.slide.lock.ObjectLockedException;
31  import org.apache.slide.security.AccessDeniedException;
32  import org.apache.slide.structure.LinkedObjectNotFoundException;
33  import org.apache.slide.structure.ObjectNotFoundException;
34  
35  /**
36   * An interface that allows custom components to observe and intercept 
37   * storage, retrieval and removal of content.
38   * 
39   * <p>
40   *   Multiple <code>ContentInterceptors</code> can be associated with a single 
41   *   <code>Namespace</code>. They are typically configured in the 
42   *   <code>&lt;configuration&gt;</code> section of the domain configuration 
43   *   file like this:
44   * </p>
45   * <p><code>
46   * &nbsp;&lt;content-interceptor class="com.acme.MyContentInterceptor"&gt;
47   * <br>
48   * &nbsp;&nbsp;&lt;parameter name="myParam1"&gt;someValue&lt;/parameter&gt;
49   * <br>
50   * &nbsp;&nbsp;&lt;parameter name="myParam2"&gt;anotherValue&lt;/parameter&gt;
51   * <br>
52   * &nbsp;&lt;/content-interceptor&gt;
53   * </code></p>
54   * <p>
55   *   As you can see, <code>ContentInterceptors</code> can be configured with 
56   *   parameters. This is optional, and exactly which parameters are available 
57   *   depends on the specific  <code>ContentInterceptor</code> implementation.
58   * </p>
59   * <p>
60   *   <code>ContentInterceptor</code> implementations must provide a public 
61   *   constructor without arguments, so that instances of the class can be 
62   *   instantiated at startup. In addition, implementors should pay attention 
63   *   to this minimal lifecycle definition:
64   *   <ul>
65   *     <li>When the namespace is being configured, <code>setParameters</code> 
66   *     will be called with a <code>java.util.Hashtable</code> containing the 
67   *     parameter names and values as specified in the configuration.</li>
68   *     <li>When configuration is completed, <code>setNamespace</code> will be 
69   *     called, passing in a <code>NamespaceAccessToken</code> than can later 
70   *     be used by the <code>ContentInterceptor</code> to perform its deeds 
71   *     (like logging to the namespace logger).</li>
72   *     <li>After that, any of the <code>preXXX</code> and <code>postXXX</code> 
73   *     methods will be called as soon as the associated event occurs.</li>
74   *  </ul>
75   * </p>
76   * <p>
77   *   The signatures of the <code>preXXX</code> and <code>postXXX</code> specify
78   *   a wide range of exceptions that can be thrown. If such an exception is 
79   *   thrown it will be propagated up to the the API client. In the case of the 
80   *   <code>preXXX</code> the started operation will be terminated. So be sure 
81   *   to handle all exceptions that shouldn't be propagated back into the core 
82   *   core API - and thus possibly influence success of the operation - 
83   *   yourself.
84   * </p>
85   * 
86   */
87  public interface ContentInterceptor {
88      
89      
90      // ---------------------------------------------------------------- Methods
91      
92      
93      /**
94       * This method will be called just before the content of a node is stored.
95       * 
96       * @param token                 the SlideToken
97       * @param revisionDescriptors   revision tree of the content to be stored
98       * @param revisionDescriptor    revision descriptor of the content to be 
99       *                              stored
100      * @param revisionContent       the actual content to be stored
101      * @throws AccessDeniedException            if access to a resource has 
102      *                                          been denied
103      * @throws ObjectNotFoundException          if an object could not be found
104      * @throws LinkedObjectNotFoundException    if an object linked to by 
105      *                                          another object could not be 
106      *                                          found
107      * @throws ObjectLockedException            if an object is locked
108      * @throws ServiceAccessException           low-level service failure
109      */
110     public void preStoreContent
111         (SlideToken token, NodeRevisionDescriptors revisionDescriptors,
112          NodeRevisionDescriptor revisionDescriptor,
113          NodeRevisionContent revisionContent)
114         throws AccessDeniedException, ObjectNotFoundException,
115                LinkedObjectNotFoundException, ObjectLockedException,
116                ServiceAccessException;
117     
118     
119     /**
120      * This method will be called just after the content of a node was stored.
121      * 
122      * @param token                 the SlideToken
123      * @param revisionDescriptors   revision tree of the content that has been 
124      *                              stored
125      * @param revisionDescriptor    revision descriptor of the content that 
126      *                              has  been stored
127      * @param revisionContent       the actual content that has been stored
128      * @throws AccessDeniedException            if access to a resource has 
129      *                                          been denied
130      * @throws ObjectNotFoundException          if an object could not be found
131      * @throws LinkedObjectNotFoundException    if an object linked to by 
132      *                                          another object could not be 
133      *                                          found
134      * @throws ObjectLockedException            if an object is locked
135      * @throws ServiceAccessException           low-level service failure
136      */
137     public void postStoreContent
138         (SlideToken token, NodeRevisionDescriptors revisionDescriptors,
139          NodeRevisionDescriptor revisionDescriptor,
140          NodeRevisionContent revisionContent)
141         throws AccessDeniedException, ObjectNotFoundException,
142                LinkedObjectNotFoundException, ObjectLockedException,
143                ServiceAccessException;
144     
145     
146     /**
147      * This method will be called just before content is retrieved, or the 
148      * descriptor of a particular revision is retrieved.
149      * 
150      * @param token                 the SlideToken
151      * @param revisionDescriptors   revision tree of the descriptor that 
152      *                              should be retrieved, or <code>null</code> 
153      *                              if the content should be retrieved
154      * @param revisionNumber        revision number of the descriptor that 
155      *                              should be retrieved, or <code>null</code> 
156      *                              if the content should be retrieved
157      * @param revisionDescriptor    revision descriptor of the content that 
158      *                              should be retrieved, or <code>null</code> 
159      *                              if the descriptor will be retrieved
160      * @throws AccessDeniedException            if access to a resource has 
161      *                                          been denied
162      * @throws ObjectNotFoundException          if an object could not be found
163      * @throws LinkedObjectNotFoundException    if an object linked to by 
164      *                                          another object could not be 
165      *                                          found
166      * @throws ObjectLockedException            if an object is locked
167      * @throws ServiceAccessException           low-level service failure
168      */
169     public void preRetrieveContent
170         (SlideToken token, NodeRevisionDescriptors revisionDescriptors,
171          NodeRevisionNumber revisionNumber,
172          NodeRevisionDescriptor revisionDescriptor)
173         throws AccessDeniedException, ObjectNotFoundException,
174                LinkedObjectNotFoundException, ObjectLockedException,
175                ServiceAccessException;
176     
177     
178     /**
179      * This method will be called just after retrieving content, or the 
180      * descriptor of a particular revision.
181      * 
182      * @param token                 the SlideToken
183      * @param revisionDescriptors   revision tree of the descriptor that has 
184      *                              been retrieved, or <code>null</code> when 
185      *                              the content has been retrieved
186      * @param revisionDescriptor    revision descriptor of the content that has
187      *                              been retrieved, or the descriptor itself 
188      *                              has been retrieved
189      * @param revisionContent       the actual content that has been retrieved,
190      *                              or <code>null</code> when the descriptor 
191      *                              has been retrieved
192      * @throws AccessDeniedException            if access to a resource has 
193      *                                          been denied
194      * @throws ObjectNotFoundException          if an object could not be found
195      * @throws LinkedObjectNotFoundException    if an object linked to by 
196      *                                          another object could not be 
197      *                                          found
198      * @throws ObjectLockedException            if an object is locked
199      * @throws ServiceAccessException           low-level service failure
200      */
201     public void postRetrieveContent
202         (SlideToken token, NodeRevisionDescriptors revisionDescriptors,
203          NodeRevisionDescriptor revisionDescriptor,
204          NodeRevisionContent revisionContent)
205         throws AccessDeniedException, ObjectNotFoundException,
206                LinkedObjectNotFoundException, ObjectLockedException,
207                ServiceAccessException;
208     
209     
210     /**
211      * This method will be called just before content will get removed, either 
212      * of all revisions of a node, or of only one particular revision.
213      * 
214      * @param token                 the SlideToken
215      * @param revisionDescriptors   revision tree of the content that will be 
216      *                              removed, or <code>null</code> if a only a 
217      *                              particular revision should be removed
218      * @param revisionDescriptor    revision descriptor of the content that 
219      *                              will be removed, or <code>null</code> if 
220      *                              all revisions of a node should be removed
221      * @throws AccessDeniedException            if access to a resource has 
222      *                                          been denied
223      * @throws ObjectNotFoundException          if an object could not be found
224      * @throws LinkedObjectNotFoundException    if an object linked to by 
225      *                                          another object could not be 
226      *                                          found
227      * @throws ObjectLockedException            if an object is locked
228      * @throws ServiceAccessException           low-level service failure
229      */
230     public void preRemoveContent   
231         (SlideToken token, NodeRevisionDescriptors revisionDescriptors,
232          NodeRevisionDescriptor revisionDescriptor)
233         throws AccessDeniedException, ObjectNotFoundException,
234                LinkedObjectNotFoundException, ObjectLockedException,
235                ServiceAccessException;
236     
237     
238     /**
239      * This method will be called just after content has been removed, either 
240      * of all revisions of a node, or of only one particular revision.
241      * 
242      * @param token                 the SlideToken
243      * @param revisionDescriptors   revision tree of the content that has been 
244      *                              removed, or <code>null</code> if a only a 
245      *                              particular revision has been removed
246      * @param revisionDescriptor    revision descriptor of the content that 
247      *                              has been removed, or <code>null</code> if 
248      *                              all revisions of a node have been removed
249      * @throws AccessDeniedException            if access to a resource has 
250      *                                          been denied
251      * @throws ObjectNotFoundException          if an object could not be found
252      * @throws LinkedObjectNotFoundException    if an object linked to by 
253      *                                          another object could not be 
254      *                                          found
255      * @throws ObjectLockedException            if an object is locked
256      * @throws ServiceAccessException           low-level service failure
257      */
258     public void postRemoveContent   
259         (SlideToken token, NodeRevisionDescriptors revisionDescriptors,
260          NodeRevisionDescriptor revisionDescriptor)
261         throws AccessDeniedException, ObjectNotFoundException,
262                LinkedObjectNotFoundException, ObjectLockedException,
263                ServiceAccessException;
264     
265     
266     /**
267      * The <code>setNamespace</code> method will be called during 
268      * initialization of the ContextInterceptor.
269      * 
270      * @param nat   the access token to the namespace this ContentInterceptor 
271      *              has been associated with
272      */
273     public void setNamespace
274         (NamespaceAccessToken nat);
275     
276     
277     /**
278      * This method is called during initialization of the ContentInterceptor 
279      * to allow parameterization from the configuration. If no parameters have 
280      * been specified, the Hashtable will be empty
281      *
282      * @param parameters    Hashtable containing the parameters' names as keys 
283      *                      and the associated parameter values as values, 
284      *                      both of type <code>java.lang.String</code>
285      */
286     public void setParameters
287         (Hashtable   parameters);
288     
289     
290 }
291 
292
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags