Class | Line # | Actions | |||||
---|---|---|---|---|---|---|---|
Event | 74 | 0 | - | 0 | 0 | ||
Event.Importance | 77 | 0 | - | 0 | 0 |
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 org.xwiki.eventstream; | |
21 | ||
22 | import java.net.URL; | |
23 | import java.util.Date; | |
24 | import java.util.Map; | |
25 | ||
26 | import org.xwiki.model.reference.DocumentReference; | |
27 | import org.xwiki.model.reference.EntityReference; | |
28 | import org.xwiki.model.reference.SpaceReference; | |
29 | import org.xwiki.model.reference.WikiReference; | |
30 | ||
31 | /** | |
32 | * A recorded event that occurred at some point in the wiki. | |
33 | * <p> | |
34 | * Events are identified by: | |
35 | * <ul> | |
36 | * <li>an {@link #getId() identifier} unique for each event</li> | |
37 | * <li>a {@link #getGroupId() group identifier} used for all the events caused during the same action</li> | |
38 | * <li>the {@link #getDate() exact date and time} when the event occurred</li> | |
39 | * <li>an {@link #getImportance() importance} which allows to order events in the same group, or in the same stream</li> | |
40 | * </ul> | |
41 | * Events contain: | |
42 | * <ul> | |
43 | * <li>a {@link #getTitle() title}</li> | |
44 | * <li>a {@link #getBody() body}</li> | |
45 | * <li>and a map of {@link #getParameters() parameters}</li> | |
46 | * </ul> | |
47 | * Events are categorized into: | |
48 | * <ol> | |
49 | * <li>the {@link #getApplication() the application} that created them, like blog, user statuses, or the general wiki</li> | |
50 | * <li>an {@link #getStream() eventual sub-stream} inside the application, for example a space for wiki events, or a | |
51 | * certain group for user statuses</li> | |
52 | * <li>the {@link #getType() particular type} of event, like adding a comment, updating an attachment, setting a new | |
53 | * user status</li> | |
54 | * </ol> | |
55 | * Events target: | |
56 | * <ol> | |
57 | * <li>the {@link #getWiki() wiki},</li> | |
58 | * <li>the {@link #getSpace() space},</li> | |
59 | * <li>and the {@link #getDocument() document} affected by the event,</li> | |
60 | * <li>and an eventual {@link #getRelatedEntity() entity} inside the document, for example an individual attachment for | |
61 | * attachment events, or an individual object for comment events.</li> | |
62 | * </ol> | |
63 | * Events can store some more information about the context in which they occur: | |
64 | * <ul> | |
65 | * <li>the {@link #getUser() user} that caused the event</li> | |
66 | * <li>the {@link #getDocumentVersion() version} of the target document at the time that the event occurred</li> | |
67 | * <li>the {@link #getDocumentTitle() display title} of the target document at the time that the event occurred</li> | |
68 | * <li>the {@link #getUrl() requested URL} that caused the event</li> | |
69 | * </ul> | |
70 | * | |
71 | * @version $Id: eab929c0668374cba04377e42f398d84e547ee2a $ | |
72 | * @since 3.0M2 | |
73 | */ | |
74 | public interface Event | |
75 | { | |
76 | /** The importance of an event. */ | |
77 | enum Importance | |
78 | { | |
79 | /** An event of very low importance in the current event group, usually a side effect of another event. */ | |
80 | BACKGROUND, | |
81 | ||
82 | /** An event of little importance, not relevant for most users. */ | |
83 | MINOR, | |
84 | ||
85 | /** The default priority for events. */ | |
86 | MEDIUM, | |
87 | ||
88 | /** An important event that stands out in the event stream. */ | |
89 | MAJOR, | |
90 | ||
91 | /** A critical event that signals a major change or problem in the wiki. */ | |
92 | CRITICAL | |
93 | } | |
94 | ||
95 | /** | |
96 | * Each event has a unique ID. | |
97 | * | |
98 | * @return the unique ID of the event | |
99 | */ | |
100 | String getId(); | |
101 | ||
102 | /** | |
103 | * @param id the unique ID of the event to set | |
104 | * @see #getId() | |
105 | */ | |
106 | void setId(String id); | |
107 | ||
108 | /** | |
109 | * Multiple events can correspond to the same activity, so events can be grouped under the same GroupID. | |
110 | * | |
111 | * @return the event group ID | |
112 | */ | |
113 | String getGroupId(); | |
114 | ||
115 | /** | |
116 | * @param id the event group ID | |
117 | * @see #getGroupId() | |
118 | */ | |
119 | void setGroupId(String id); | |
120 | ||
121 | /** | |
122 | * An event happens at a precise date. | |
123 | * | |
124 | * @return the event date | |
125 | */ | |
126 | Date getDate(); | |
127 | ||
128 | /** | |
129 | * @param date the event date | |
130 | * @see #getDate() | |
131 | */ | |
132 | void setDate(Date date); | |
133 | ||
134 | /** | |
135 | * Different events can have a different importance. This allows to determine which events are more or less | |
136 | * important in the same event group, or which events are important in the stream. For example, annotation automatic | |
137 | * updates are less important in a group of changes triggered by a document update, while a major version is more | |
138 | * important than a minor version. | |
139 | * | |
140 | * @return the importance of the event | |
141 | */ | |
142 | Importance getImportance(); | |
143 | ||
144 | /** | |
145 | * @param importance the importance of the event | |
146 | * @see #getImportance() | |
147 | */ | |
148 | void setImportance(Importance importance); | |
149 | ||
150 | /** | |
151 | * A name for the event. | |
152 | * | |
153 | * @return the title of the event | |
154 | */ | |
155 | String getTitle(); | |
156 | ||
157 | /** | |
158 | * @param title the title of the event | |
159 | * @see #getTitle() | |
160 | */ | |
161 | void setTitle(String title); | |
162 | ||
163 | /** | |
164 | * A larger section of text where the event can store some data. | |
165 | * | |
166 | * @return the body of the event | |
167 | */ | |
168 | String getBody(); | |
169 | ||
170 | /** | |
171 | * @param body the body of the event | |
172 | * @see #getBody() | |
173 | */ | |
174 | void setBody(String body); | |
175 | ||
176 | /** | |
177 | * Events can be triggered by different applications, not only the main wiki update events: user statuses, blog | |
178 | * pingbacks, new extension added... | |
179 | * | |
180 | * @return the application name | |
181 | */ | |
182 | String getApplication(); | |
183 | ||
184 | /** | |
185 | * @param application the application Name | |
186 | * @see #getApplication() | |
187 | */ | |
188 | void setApplication(String application); | |
189 | ||
190 | /** | |
191 | * Events can happen in different contexts; for example, wiki activity events happen in different spaces, user | |
192 | * statuses are targeted to different groups. | |
193 | * | |
194 | * @return the stream name | |
195 | */ | |
196 | String getStream(); | |
197 | ||
198 | /** | |
199 | * @param stream the stream Name | |
200 | * @see #getStream() | |
201 | */ | |
202 | void setStream(String stream); | |
203 | ||
204 | /** | |
205 | * Events have different types: adding a comment, updating an attachment, importing an application, etc. | |
206 | * | |
207 | * @return The type of the event | |
208 | */ | |
209 | String getType(); | |
210 | ||
211 | /** | |
212 | * @param type The type of the event | |
213 | * @see #getType() | |
214 | */ | |
215 | void setType(String type); | |
216 | ||
217 | /** | |
218 | * In a wiki farm, each event happens in one of the wikis. | |
219 | * | |
220 | * @return the wiki name in which the event was created | |
221 | */ | |
222 | WikiReference getWiki(); | |
223 | ||
224 | /** | |
225 | * @param wiki the wiki name in which the event was created | |
226 | * @see #getWiki() | |
227 | */ | |
228 | void setWiki(WikiReference wiki); | |
229 | ||
230 | /** | |
231 | * Document-related events target a certain document, and documents belong to a space; this is the space of the | |
232 | * target document. | |
233 | * | |
234 | * @return the space in which the event was created | |
235 | */ | |
236 | SpaceReference getSpace(); | |
237 | ||
238 | /** | |
239 | * @param space the space in which the event was created | |
240 | * @see #getSpace() | |
241 | */ | |
242 | void setSpace(SpaceReference space); | |
243 | ||
244 | /** | |
245 | * Document-related events target a certain document. | |
246 | * | |
247 | * @return the document related to the event | |
248 | */ | |
249 | DocumentReference getDocument(); | |
250 | ||
251 | /** | |
252 | * @param document the document related to the event | |
253 | * @see #getDocument() | |
254 | */ | |
255 | void setDocument(DocumentReference document); | |
256 | ||
257 | /** | |
258 | * For events related to documents, this field records the version of the document at the time when the event | |
259 | * occurred. | |
260 | * | |
261 | * @return the document version when the event occurred | |
262 | */ | |
263 | String getDocumentVersion(); | |
264 | ||
265 | /** | |
266 | * @param version the document version when the event occurred | |
267 | * @see #getDocumentVersion() | |
268 | */ | |
269 | void setDocumentVersion(String version); | |
270 | ||
271 | /** | |
272 | * Some events may be related to a more specific entity in the target document, like an attachment or an object, or | |
273 | * may relate to another document besides the {@link #getDocument() main related document}. The result of this | |
274 | * method depends on the actual event type. | |
275 | * | |
276 | * @return the eventual entity related to the event, may be {@code null} | |
277 | */ | |
278 | EntityReference getRelatedEntity(); | |
279 | ||
280 | /** | |
281 | * @param entity the eventual entity related to the event | |
282 | * @see #getRelatedEntity() | |
283 | */ | |
284 | void setRelatedEntity(EntityReference entity); | |
285 | ||
286 | /** | |
287 | * Event usually occur as the result of a registered user activity. | |
288 | * | |
289 | * @return the user creating the event | |
290 | */ | |
291 | DocumentReference getUser(); | |
292 | ||
293 | /** | |
294 | * @param user the user creating the event | |
295 | * @see #getUser() | |
296 | */ | |
297 | void setUser(DocumentReference user); | |
298 | ||
299 | /** | |
300 | * If an event happens in an URL-accessible location (a document), or if the event itself can be seen at a given | |
301 | * URL, this field stores that URL. | |
302 | * | |
303 | * @return the URL related to the event | |
304 | */ | |
305 | URL getUrl(); | |
306 | ||
307 | /** | |
308 | * @param url the URL related to the event | |
309 | * @see #getUrl() | |
310 | */ | |
311 | void setUrl(URL url); | |
312 | ||
313 | /** | |
314 | * The document title is usually more important than the document name. Since getting the title of a document | |
315 | * version is a difficult task, store it in the event for faster and safer access. | |
316 | * | |
317 | * @return the title of the related document when the event occurred. | |
318 | */ | |
319 | String getDocumentTitle(); | |
320 | ||
321 | /** | |
322 | * @param title the title of the related document when the event occurred. | |
323 | * @see #getDocumentTitle() | |
324 | */ | |
325 | void setDocumentTitle(String title); | |
326 | ||
327 | /** | |
328 | * @return the named parameters associated with this event as key/value pairs. | |
329 | */ | |
330 | Map<String, String> getParameters(); | |
331 | ||
332 | /** | |
333 | * @param parameters the parameters to associate to the event. | |
334 | * @see #getParameters() | |
335 | */ | |
336 | void setParameters(Map<String, String> parameters); | |
337 | } |