KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > com > ivata > groupware > business > library > Library


1 /*
2  * Copyright (c) 2001 - 2005 ivata limited.
3  * All rights reserved.
4  * -----------------------------------------------------------------------------
5  * ivata groupware may be redistributed under the GNU General Public
6  * License as published by the Free Software Foundation;
7  * version 2 of the License.
8  *
9  * These programs are free software; you can redistribute them and/or
10  * modify them under the terms of the GNU General Public License
11  * as published by the Free Software Foundation; version 2 of the License.
12  *
13  * These programs are distributed in the hope that they will be useful,
14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
16  *
17  * See the GNU General Public License in the file LICENSE.txt for more
18  * details.
19  *
20  * If you would like a copy of the GNU General Public License write to
21  *
22  * Free Software Foundation, Inc.
23  * 59 Temple Place - Suite 330
24  * Boston, MA 02111-1307, USA.
25  *
26  *
27  * To arrange commercial support and licensing, contact ivata at
28  * http://www.ivata.com/contact.jsp
29  * -----------------------------------------------------------------------------
30  * $Log: Library.java,v $
31  * Revision 1.4 2005/04/29 02:48:16 colinmacleod
32  * Data bugfixes.
33  * Changed primary key back to Integer.
34  *
35  * Revision 1.3 2005/04/10 20:09:44 colinmacleod
36  * Added new themes.
37  * Changed id type to String.
38  * Changed i tag to em and b tag to strong.
39  * Improved PicoContainerFactory with NanoContainer scripts.
40  *
41  * Revision 1.2 2005/04/09 17:19:43 colinmacleod
42  * Changed copyright text to GPL v2 explicitly.
43  *
44  * Revision 1.1.1.1 2005/03/10 17:51:55 colinmacleod
45  * Restructured ivata op around Hibernate/PicoContainer.
46  * Renamed ivata groupware.
47  *
48  * Revision 1.7 2004/11/12 18:16:06 colinmacleod
49  * Ordered imports.
50  *
51  * Revision 1.6 2004/11/12 15:57:15 colinmacleod
52  * Removed dependencies on SSLEXT.
53  * Moved Persistence classes to ivata masks.
54  *
55  * Revision 1.5 2004/09/30 14:59:06 colinmacleod
56  * Added methods to sanitize the entire library and update the search index.
57  *
58  * Revision 1.4 2004/07/31 10:26:38 colinmacleod
59  * Fixed comment tree.
60  *
61  * Revision 1.3 2004/07/19 22:01:31 colinmacleod
62  * Changed recent items from collection to list.
63  *
64  * Revision 1.2 2004/07/13 19:47:28 colinmacleod
65  * Moved project to POJOs from EJBs.
66  * Applied PicoContainer to services layer (replacing session EJBs).
67  * Applied Hibernate to persistence layer (replacing entity EJBs).
68  * -----------------------------------------------------------------------------
69  */

70 package com.ivata.groupware.business.library;
71
72 import java.util.List JavaDoc;
73
74 import com.ivata.groupware.admin.security.server.SecuritySession;
75 import com.ivata.groupware.business.library.comment.CommentDO;
76 import com.ivata.groupware.business.library.item.LibraryItemDO;
77 import com.ivata.groupware.business.library.topic.TopicDO;
78 import com.ivata.mask.util.SystemException;
79 import com.ivata.mask.validation.ValidationErrors;
80
81 /**
82  * <p>
83  * TODO: add a comment for this type.
84  * </p>
85  *
86  * @author Colin MacLeod
87  * <a HREF='mailto:colin.macleod@ivata.com'>colin.macleod@ivata.com</a>
88  * @since Jun 19, 2004
89  * @version $Revision: 1.4 $
90  */

91
92 public interface Library {
93     final static String JavaDoc BUNDLE_PATH = "library";
94
95     /**
96      * <p>Add a new comment to the system. The user supplied is checked, to make
97      * sure she has the necessary permission to add the comment, then the comment
98      * is added and the new primary key value (id) is returned.</p>
99      *
100      * @throws BusinessException if the user
101      * provided is not entitled to add this topic.
102      * @throws BusinessException
103      * if either the <code>subject</code>, <code>subject</code> or
104      * <code>item id</code> fields are <code>null</code>.
105      * @param securitySession mail session used to post notifications about the new
106      * comment.
107      * @param comment data object containing all values of the new
108      * object to add.
109      * @param replyToId the unique identifier of the comment this is a reply to,
110      * or <code>null</code> if this is the first comment in a thread.
111      * @return new value of the comment as it is now in the system.
112      */

113     public CommentDO addComment(final SecuritySession securitySession,
114             final CommentDO comment) throws SystemException;
115
116     /**
117      * <p>Add a new library item to the system. The <code>created</code> and
118      * <code>modified</code> timestamps are set automatically by this method
119      * (any values in <code>item</code> are ignored). The <code>user</code>,
120      * <code>createdBy<code> and <code>modifiedBy<code> fields are set to the
121      * user name you provide.</p>
122      *
123      * <p>For the topic, the <code>topicId</code> field is taken from the
124      * data object: settings for the caption and image are
125      * ignored.</p>
126      *
127      * @param userName the name of the user who wants to add the item. This is
128      * used to check user rights.
129      * @param item a data object containing all the details
130      * of the item to add.
131      * @param securitySession mail session used to post notifications about the new
132      * library item.
133      * @param comment the comment used in revision control
134      * @exception com.ivata.groupware.ejb.entity.InvalidFieldValueException
135      * if a field has an incorrect value.
136      * @exception com.ivata.groupware.ejb.entity.MandatoryFieldException
137      * if a mandatory field has no value.
138      * @exception com.ivata.groupware.ejb.entity.UserRightException if the user
139      * provided is not entitled to add this item.
140      * @return the new item data object, with the details as they
141      * now are in the adressbook.
142      */

143     public LibraryItemDO addItem(final SecuritySession securitySession,
144             final LibraryItemDO item,
145             final String JavaDoc comment) throws SystemException;
146
147     /**
148      * <p>Add a new topic to the system. The user supplied is checked, to make
149      * sure she has the necessary permission to add the topic, then the topic
150      * is added and the new primary key value (id) is returned.</p>
151      *
152      * @exception com.ivata.groupware.ejb.entity.UserRightException if the user
153      * provided is not entitled to add this topic.
154      * @exception com.ivata.groupware.ejb.entity.InvalidFieldValueException
155      * if either the <code>caption</code> or <code>image</code> fields are
156      * <code>null</code>.
157      * @param userName the user who is trying to add the topic (to check the
158      * user right permissions).
159      * @param topic details of new TOPIC.
160      *
161      * @return TopicDO which was added.
162      */

163     public TopicDO addTopic(final SecuritySession securitySession,
164             final TopicDO topic) throws SystemException;
165
166     /**
167      * <p>Amend an existing comment in the system. The user supplied is
168      * checked, to make sure she has the necessary permission to amend the
169      * comment, then the comment is changed and the current comment values
170      * are returned, as they now are in the database.</p>
171      *
172      * @exception com.ivata.groupware.ejb.entity.UserRightException if the user
173      * provided is not entitled to add this topic.
174      * @exception com.ivata.groupware.ejb.entity.MandatoryFieldException
175      * if the <code>id</code> field is <code>null</code>.
176      * @param userName the user who is trying to add the comment (to check the
177      * user right permissions).
178      * @param comment data object containing all values of the
179      * object to amend.
180      * @param securitySession mail session used to post notifications about the amended
181      * comment.
182      * @return new value of the comment as it is now in the system.
183      */

184     public CommentDO amendComment(final SecuritySession securitySession,
185             final CommentDO comment) throws SystemException;
186
187     /**
188      * <p>Amend an existing library item in the system. The
189      * <code>modified</code> timestamp is set automatically by this method
190      * (any values in <code>item</code> are ignored). Values for the
191      * <code>created</code> timestamp are not changed.</p>
192      *
193      * <p>The <code>modifiedBy<code> field is set to the user name you
194      * provide.</p>
195      *
196      * <p>For the topic, the <code>topicId</code> field is taken from the
197      * data object: settings for the caption and image are
198      * ignored.</p>
199      *
200      * @param userName the name of the user who wants to amend the item. This is
201      * used to check user rights.
202      * @param item a data object containing all the details
203      * of the item to amend.
204      * @param securitySession mail server used to post notifications about the amended
205      * library item.
206      * @param comment the comment used in revision control
207      * @exception com.ivata.groupware.ejb.entity.MandatoryFieldException
208      * if a mandatory field has no value.
209      * @exception com.ivata.groupware.ejb.entity.UserRightException if the user
210      * provided is not entitled to add this item.
211      * @return the new item data object, with the details as they
212      * now are in the adressbook.
213      */

214     public LibraryItemDO amendItem(final SecuritySession securitySession,
215             final LibraryItemDO item,
216             final String JavaDoc comment) throws SystemException;
217
218     /**
219      * <p>Amend an existing topic in the system. The user supplied is checked,
220      * to make sure she has the necessary permission to amend the topic, then
221      * the topic is changed.</p>
222      *
223      * @exception com.ivata.groupware.ejb.entity.UserRightException if the user
224      * provided is not entitled to amend this topic.
225      * @exception com.ivata.groupware.ejb.entity.InvalidFieldValueException
226      * if the id provided is <code>null</code>.
227      * @param userName the user who is trying to add the topic (to check the
228      * user right permissions).
229      * @param topic details of TOPIC.
230      *
231      * @return TopicDO which was amend
232      */

233     public TopicDO amendTopic(final SecuritySession securitySession,
234             final TopicDO topic) throws SystemException;
235     /**
236      * <p>
237      * Find out how many comments exists in total for a library item.
238      * </p>
239      *
240      * @param integerParam unique identifier for the item to count comments for.
241      * @return Total number of comments for the library item specified.
242      */

243     public int countCommentsForItem(final SecuritySession securitySession,
244             Integer JavaDoc integerParam)
245             throws SystemException;
246
247     /**
248      * <p>Locate a list of top-level comments in a specificy item. Note:
249      * this does not include comments which are replies - only top-level
250      * comments</p>
251      *
252      * @param integerParam the unique identifier of comment item to locate.
253      * @return data object containing all values of the
254      * object as they are now in the system.
255      */

256     public List JavaDoc findCommentByItem(final
257             SecuritySession securitySession,
258             Integer JavaDoc integerParam)
259             throws SystemException;
260
261     /**
262      * <p>Locate a list of comments in the system by their parents.</p>
263      *
264      * @param integerParam the unique identifier of parent comment to locate.
265      * @return data object containing all values of the
266      * object as they are now in the system.
267      */

268     public List JavaDoc findCommentByParent(final
269             SecuritySession securitySession,
270             Integer JavaDoc integerParam)
271             throws SystemException;
272
273     /**
274      * <p>Locate a comment in the system by its unique identifier, and return
275      * all the comment values.</p>
276      *
277      * @exception com.ivata.groupware.ejb.entity.MandatoryFieldException
278      * if the <code>id</code> field is <code>null</code>.
279      * @param id the unique identifier of the comment to locate.
280      * @return data object containing all values of the
281      * object as they are now in the system.
282      */

283     public CommentDO findCommentByPrimaryKey(final
284             SecuritySession securitySession,
285             final Integer JavaDoc id)
286             throws SystemException;
287
288     /**
289      * <p>Find an item in the library by its unique identifier.</p>
290      *
291      * @param id the unique identifier of the library item to find.
292      * @return the library item data object which matches this id,
293      * with the details as they now are in the library.
294      */

295     public LibraryItemDO findItemByPrimaryKey(final
296             SecuritySession securitySession,
297             final Integer JavaDoc id)
298             throws SystemException;
299
300     /**
301      * <p>This merhod searches for an item by revision.</p>
302      *
303      * @param rev revision number
304      * @param userName user who is doing this
305      * @return
306      */

307     public LibraryItemDO findItemByRevision(final
308             SecuritySession securitySession,
309             final String JavaDoc itemId,
310             final String JavaDoc rev)
311             throws SystemException;
312
313     /**
314      * <p>Find items sorted by modification date/time, to the count provided in
315      * the parameter. If there are less items in the library than
316      * <code>count</code>, then all library items are returned.</p>
317      *
318      * <p>The items are filtered using a view, so that only those items with the
319      * <code>access</code> level indicated are shown for the user requested.</p>
320      *
321      * @param count the total number of items to return. Specify
322      * <code>null</code> to return all items.
323      * @param userName the user to display results for. The results filtered so
324      * that only those items are return which the user is entitled to see.
325      * @param access the access level which the user should see. This is defined
326      * as one of the constants in {@link
327      * com.ivata.groupware.business.addressbook.person.user.group.right.RightConstants
328      * RightConstants}.
329      * @param topicId unique identifier of the topic to filter items for, or all
330      * topics, if <code>null</code>.
331      * @return a <code>Collection</code> of all of the item as {@link
332      * LibraryItemDO item dependent value}
333      * instances.
334      */

335     public List JavaDoc findRecentItems(final SecuritySession securitySession,
336             final Integer JavaDoc count,
337             final Integer JavaDoc access,
338             final Integer JavaDoc topicId)
339             throws SystemException;
340
341     /**
342      * <p>when we need to find library item by meeting ID</p>
343      *
344      * @return libraryItemDO
345      */

346     public TopicDO findTopicByPrimaryKey(
347             final
348             SecuritySession securitySession,
349             final Integer JavaDoc id)
350             throws SystemException;
351
352     /**
353      * <p>Find all topics with the given access rights for the user name
354      * provided.</p>
355      *
356      * @param userName the user to display results for. The results filtered so
357      * that only those topics are return which the user is entitled to access.
358      * @param access the access level which the user should see. This is defined
359      * as one of the constants in {@link
360      * com.ivata.groupware.business.addressbook.person.user.group.right.RightConstants
361      * RightConstants}.
362      * @param detail, at this moment we are trying to find Topics for :
363      * - add, amend, delete and view LIBRARY ITEMS
364      * - amend, delete and view TOPICS
365      * @return a <code>List</code> containing two <code>Map</code>s. The map
366      * in element <code>0</code> contains a <code>Map</code> of all of the
367      * topic captions. The map in element <code>1</code> contains a
368      * <code>Map</code> of all of the topic images. In each <code>Map</code>,
369      * the key is topic id.
370      */

371     public List JavaDoc findTopics(final SecuritySession securitySession) throws SystemException;
372
373     /**
374      * <p>Find all comments to which there has been no reply.</p>
375      * @param userName
376      * @param count
377      * @return
378      */

379     public List JavaDoc findUnacknowledgedComments(final
380             SecuritySession securitySession,
381             final Integer JavaDoc count)
382             throws SystemException;
383
384     /**
385      * <p>Remove an existing comment from the system. The user supplied is
386      * checked, to make sure she has the necessary permission to remove the
387      * comment, then the comment is removed.</p>
388      *
389      * @exception com.ivata.groupware.ejb.entity.UserRightException if the user
390      * provided is not entitled to add this topic.
391      * @exception com.ivata.groupware.ejb.entity.MandatoryFieldException
392      * if the <code>id</code> field is <code>null</code>.
393      * @param userName the user who is trying to add the comment (to check the
394      * user right permissions).
395      * @param comment data object containing all values of the
396      * object to amend. Only the <code>id</code> field is read.
397      */

398     public void removeComment(final SecuritySession securitySession,
399             final CommentDO comment) throws SystemException;
400
401     /**
402      * <p>Remove a library item to the system. The item with the id specified in
403      * <code>item</code> is removed.</p>
404      *
405      * @param userName the name of the user who wants to add the item. This is
406      * used to check user rights.
407      * @param item a data object containing all the details
408      * of the item to remove. Only the <code>id</code> from this object is
409      * actually used.
410      * @exception com.ivata.groupware.ejb.entity.UserRightException if the user
411      * provided is not entitled to add this item.
412      */

413     public void removeItem(final SecuritySession securitySession,
414             final LibraryItemDO item) throws SystemException;
415
416     /**
417      * <p>Remove a topic from the system. The user supplied is checked,
418      * to make sure she has the necessary permission to remove the topic, then
419      * the topic is removed.</p>
420      *
421      * @exception com.ivata.groupware.ejb.entity.UserRightException if the user
422      * provided is not entitled to remove this topic.
423      * @exception com.ivata.groupware.ejb.entity.InvalidFieldValueException
424      * if the id provided is <code>null</code> or doesn't exist.
425      * @param userName the user who is trying to add the topic (to check the
426      * user right permissions).
427      * @param topic topic which we are going to remove.
428      */

429     public void removeTopic(final SecuritySession securitySession,
430             final TopicDO topic) throws SystemException;
431
432     /**
433      * <p>This methos is reverting item to older version, It's mean that it will check OUT from CVS and call setDO with it.</p>
434      * @param itemId
435      * @param revision
436      * @param userName
437      * @return
438      */

439     public LibraryItemDO revertItemToRevision(final
440             SecuritySession securitySession,
441             final String JavaDoc itemId,
442             final String JavaDoc revision,
443             final String JavaDoc comment) throws SystemException;
444
445     /**
446      * <p>
447      * Sanitize all library contents.
448      * </p>
449      *
450      * @param item
451      * @param persistenceSession
452      */

453     public void sanitize(SecuritySession securitySession)
454         throws SystemException;
455
456     /**
457      * <p>
458      * Re-index all library contents (items and comments) in the search engine.
459      * This is useful after an upgrade, if the search functionality has changed.
460      * </p>
461      */

462     public void updateSearchIndex (SecuritySession securitySession)
463             throws SystemException ;
464
465     /**
466      * <p>Confirm all of the elements of the comment are valid before it
467      * is submitted.</p>
468      *
469      * @param comment data object to check for consistency and
470      * completeness.
471      * @return a collection of validation errors if any of the
472      * mandatory fields are missing, or if fields contain invalid values.
473      */

474     public ValidationErrors validate(final SecuritySession securitySession,
475             final CommentDO comment);
476
477     /**
478      * <p>Confirm all of the elements of the item are present and valid,
479      * before the item is submitted.</p>
480      *
481      * @param item data object to check for consistency and
482      * completeness.
483      * @return a collection of validation errors if any of the
484      * mandatory fields are missing, or if fields contain invalid values.
485      */

486     public ValidationErrors validate(final SecuritySession securitySession,
487             final LibraryItemDO item);
488
489     /**
490      * <p>Confirm all of the elements of the topic are present and valid,
491      * before the topic is submitted.</p>
492      *
493      * @param topic data object to check for consistency and
494      * completeness.
495      * @return a collection of validation errors if any of the
496      * mandatory fields are missing, or if fields contain invalid values.
497      */

498     public ValidationErrors validate(final SecuritySession securitySession,
499             final TopicDO topic);
500 }
Popular Tags