1. Project Clover database Tue Dec 20 2016 21:24:09 CET
  2. Package com.xpn.xwiki.plugin

File XWikiPluginInterface.java

 

Code metrics

0
0
0
1
229
24
0
-
-
0
-

Classes

Class Line # Actions
XWikiPluginInterface 61 0 - 0 0
-1.0 -
 

Contributing tests

No tests hitting this source file were found.

Source view

1    /*
2    * See the NOTICE file distributed with this work for additional
3    * information regarding copyright ownership.
4    *
5    * This is free software; you can redistribute it and/or modify it
6    * under the terms of the GNU Lesser General Public License as
7    * published by the Free Software Foundation; either version 2.1 of
8    * the License, or (at your option) any later version.
9    *
10    * This software is distributed in the hope that it will be useful,
11    * but WITHOUT ANY WARRANTY; without even the implied warranty of
12    * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13    * Lesser General Public License for more details.
14    *
15    * You should have received a copy of the GNU Lesser General Public
16    * License along with this software; if not, write to the Free
17    * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
18    * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
19    */
20    package com.xpn.xwiki.plugin;
21   
22    import com.xpn.xwiki.XWikiContext;
23    import com.xpn.xwiki.XWikiException;
24    import com.xpn.xwiki.api.Api;
25    import com.xpn.xwiki.doc.XWikiAttachment;
26   
27    /**
28    * Deprecated platform extension mechanism allowing three things:
29    * <ul>
30    * <li>provide custom services usable from other parts of the platform, or as public services in Velocity scripts using
31    * a {@link PluginApi} wrapper; this can now be achieved using components for use inside Java, or using
32    * {@link org.xwiki.script.service.ScriptService} components for public scriptable APIs</li>
33    * <li>alter the request processing by implementing one or more of the hook methods that plug into the rendering engine,
34    * such as {@link #endParsing(String, XWikiContext)} or {@link #downloadAttachment(XWikiAttachment, XWikiContext)}; this
35    * can now be achieved using {@link org.xwiki.rendering.transformation.Transformation rendering transformations} for
36    * changing the rendering result, or {@link org.xwiki.observation.EventListener event listeners} for doing custom
37    * actions when different events occur</li>
38    * <li>perform extra initialization steps whenever starting the platform, or when loading each virtual wiki; this can be
39    * achieved by writing {@link org.xwiki.observation.EventListener event listeners} that wait for
40    * {@link org.xwiki.observation.event.ApplicationStartedEvent application events} or
41    * {@link org.xwiki.bridge.event.WikiEvent wiki events}</li>
42    * </ul>
43    * <p>
44    * In order for a plugin to be active, it must be registered in {@code xwiki.cfg}.
45    * </p>
46    * <p>
47    * Public scriptable APIs are implemented in a custom {@link PluginApi} wrapper, which is instantiated by calling the
48    * {@link #getPluginApi(XWikiPluginInterface, XWikiContext)} method. If a plugin doesn't need a scriptable API, it
49    * should return {@code null} instead.
50    * </p>
51    * <p>
52    * The methods of a specific plugin <strong>are called only if the actual class implements that method</strong>, so
53    * inherited methods are never called. If a plugin wants to provide an implementation for one of the hook methods, it
54    * must provide an implementation for it, even if that implementation only calls a parent method.
55    * </p>
56    *
57    * @version $Id: 8d7045844ef4917fd5f65de5e008a7a7b2a91d3e $
58    * @deprecated the plugin technology is deprecated, consider rewriting as components
59    */
60    @Deprecated
 
61    public interface XWikiPluginInterface
62    {
63    /**
64    * The name which can be used for accessing this plugin from
65    * {@link com.xpn.xwiki.XWiki#getPlugin(String, XWikiContext)}.
66    *
67    * @return the plugin name, usually a lowercase identifier
68    */
69    String getName();
70   
71    /**
72    * Get a public scriptable API that can be used to call methods of the (privileged) plugin.
73    *
74    * @param plugin the plugin instance to wrap
75    * @param context the current request context
76    * @return an instance of the corresponding API, or {@code null} if the plugin doesn't want to expose a public API
77    */
78    Api getPluginApi(XWikiPluginInterface plugin, XWikiContext context);
79   
80    /**
81    * Global initialization, called when the platform is started and the plugin list is initialized.
82    *
83    * @param context the current context, should not be stored since it will become mostly unreliable once the initial
84    * request is terminated
85    * @throws XWikiException if the plugin fails to initialize
86    */
87    void init(XWikiContext context) throws XWikiException;
88   
89    /**
90    * Initialization method called each time a virtual wiki is started, allowing plugins to perform initialization
91    * tasks needed in each wiki.
92    *
93    * @param context the current request context
94    */
95    void virtualInit(XWikiContext context);
96   
97    /**
98    * A "flush cache" method usually called by the global {@link com.xpn.xwiki.XWiki#flushCache(XWikiContext)},
99    * requesting plugins to clear their cached data. When this method is called, plugins should discard all the
100    * information they hold from the wiki and re-read it if needed.
101    *
102    * @param context the current request context
103    */
104    void flushCache(XWikiContext context);
105   
106    /**
107    * Hook method called at the start of the response generation process, before the parsing of the root template
108    * begins. This allows a plugin to initialize its per-request variables, or to modify the (velocity) context. This
109    * method is called at most once per request. It is not called at all if the response is not rendered using a
110    * velocity template, for example during the PDF export or for AJAX requests that don't send back a rendered
111    * response.
112    *
113    * @param context the current request context
114    * @see #endParsing(String, XWikiContext) the pair method called at the end of the response generation process
115    */
116    void beginParsing(XWikiContext context);
117   
118    /**
119    * Hook method, called before the 1.0 rendering engine starts processing a wiki document, after
120    * {@link #beginParsing(XWikiContext)} and before {@link #commonTagsHandler(String, XWikiContext)}. This allows a
121    * plugin to initialize its per-rendering variables, or to modify the (velocity) context. This method can be called
122    * multiple times per request, once for each time the 1.0 rendering engine is invoked. At this point the content is
123    * not yet processed by any of the rendering components.
124    *
125    * @param context the current request context
126    * @see #endRendering(XWikiContext) the pair method called at the end of the content processing
127    */
128    void beginRendering(XWikiContext context);
129   
130    /**
131    * Hook method called during the 1.0 rendering process, after {@link #beginRendering(XWikiContext)} and right before
132    * {@link #startRenderingHandler(String, XWikiContext)}. At this point the content has already been processed by all
133    * of the important rendering components (Velocity, Radeox, Groovy). The content can be altered before returning,
134    * and the rendering process will continue on the returned value.
135    *
136    * @param content the current content being rendered; already processed by Radeox, Velocity and Groovy
137    * @param context the current request context
138    * @return the processed content, must be the same as the input content if no processing is needed
139    */
140    String commonTagsHandler(String content, XWikiContext context);
141   
142    /**
143    * Hook method called during the 1.0 rendering process, after {@link #commonTagsHandler(String, XWikiContext)} and
144    * before {@link #outsidePREHandler(String, XWikiContext)}. The content can be altered before returning. This method
145    * should be avoided, since the place where the hook is used isn't actually reliable, since at this point the
146    * rendering process is almost done.
147    *
148    * @param content the current content being rendered; already processed by Radeox, Velocity and Groovy
149    * @param context the current request context
150    * @return the processed content, must be the same as the input content if no processing is needed
151    * @see #endRenderingHandler(String, XWikiContext) the pair method called after the content is processed
152    * @see #beginRendering(XWikiContext) the method called before the content has been processed by the rendering
153    * engine
154    */
155    String startRenderingHandler(String content, XWikiContext context);
156   
157    /**
158    * Hook method called during the 1.0 rendering process, once for each line of content outside {@code pre} blocks,
159    * after {@link #startRenderingHandler(String, XWikiContext)} and before
160    * {@link #endRenderingHandler(String, XWikiContext)}. The content can be altered before returning.
161    *
162    * @param line the current line being rendered; already processed by Radeox, Velocity and Groovy
163    * @param context the current request context
164    * @return the processed line, must be the same as the input content if no processing is needed
165    * @see #insidePREHandler(String, XWikiContext) the pair method called for content inside {@code pre} blocks
166    */
167    String outsidePREHandler(String line, XWikiContext context);
168   
169    /**
170    * Hook method called during the 1.0 rendering process, once for each line of content inside {@code pre} blocks,
171    * after {@link #startRenderingHandler(String, XWikiContext)} and before
172    * {@link #endRenderingHandler(String, XWikiContext)}. The content can be altered before returning.
173    *
174    * @param line the current line being rendered; already processed by Radeox, Velocity and Groovy
175    * @param context the current request context
176    * @return the processed line, must be the same as the input content if no processing is needed
177    * @see #outsidePREHandler(String, XWikiContext) the pair method called for content outside {@code pre} blocks
178    */
179    String insidePREHandler(String line, XWikiContext context);
180   
181    /**
182    * Hook method called during the 1.0 rendering process, after {@link #outsidePREHandler(String, XWikiContext)} and
183    * right before {@link #endRendering(XWikiContext)}. The content can be altered before returning, and the returned
184    * value is the one coming out of the rendering process.
185    *
186    * @param content the current content being rendered; already processed by Radeox, Velocity and Groovy
187    * @param context the current request context
188    * @return the processed content, must be the same as the input content if no processing is needed
189    * @see #startRenderingHandler(String, XWikiContext) the pair method called before the content is processed
190    * @see #endRendering(XWikiContext) the method called after the full rendering process is finished
191    */
192    String endRenderingHandler(String content, XWikiContext context);
193   
194    /**
195    * Hook method, called after the 1.0 rendering engine finished processing a wiki document. This allows a plugin to
196    * clean up its per-rendering variables, or to modify the (velocity) context. This method can be called multiple
197    * times per request, once for each time the 1.0 rendering engine is invoked. At this point the content is processed
198    * by all of the rendering components and is ready to be included in the response.
199    *
200    * @param context the current request context
201    * @see #endRenderingHandler(String, XWikiContext) allows to also alter the rendering result
202    */
203    void endRendering(XWikiContext context);
204   
205    /**
206    * Hook method called at the end of the response generation process, after the parsing of the root template is
207    * finished. This allows a plugin to clean up its per-request variables, to modify the (velocity) context, or to
208    * post-process the response. This method is called at most once per request. It is not called at all if the
209    * response is not rendered using a velocity template, for example during the PDF export or for AJAX requests that
210    * don't send back a rendered response.
211    *
212    * @param content the full response to send to the client
213    * @param context the current request context
214    * @return the post-processed content, must be the same as the input content if no processing is needed
215    * @see #beginParsing(XWikiContext) the pair method called at the start of the response generation process
216    */
217    String endParsing(String content, XWikiContext context);
218   
219    /**
220    * Plugin extension point allowing the plugin to perform modifications to an attachment when the user opens a
221    * document attachment. The plugin is passed the original attachment and it has to return the new modified
222    * attachment.
223    *
224    * @param attachment the original attachment
225    * @param context the current request context
226    * @return the modified attachment
227    */
228    XWikiAttachment downloadAttachment(XWikiAttachment attachment, XWikiContext context);
229    }