Classes

Class	Line #	Total Statements	% Filtered	Complexity	Uncovered Elements	TOTAL Coverage	Actions
XWikiPluginInterface	61	0	-	0	0	-1.0 -	Show methods

Class XWikiPluginInterface

Class XWikiPluginInterface	Line # 61	Total Statements 0	% Filtered -	Complexity 0	Uncovered Elements 0	TOTAL Coverage -1.0 -

 

Contributing tests

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
		- Uncovered Elements: 0 (0) Complexity: 0 Complexity Density: -
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		}