1. Project Clover database Tue Dec 20 2016 21:24:09 CET
  2. Package org.xwiki.eventstream

File Event.java

 

Code metrics

0
0
0
2
337
55
0
-
-
0
-

Classes

Class Line # Actions
Event 74 0 - 0 0
-1.0 -
Event.Importance 77 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 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    }