TopicDAO


1   /*
2    * Copyright (c) Rafael Steil
3    * All rights reserved.
4    * 
5    * Redistribution and use in source and binary forms, 
6    * with or without modification, are permitted provided 
7    * that the following conditions are met:
8    * 
9    * 1) Redistributions of source code must retain the above 
10   * copyright notice, this list of conditions and the 
11   * following  disclaimer.
12   * 2)  Redistributions in binary form must reproduce the 
13   * above copyright notice, this list of conditions and 
14   * the following disclaimer in the documentation and/or 
15   * other materials provided with the distribution.
16   * 3) Neither the name of "Rafael Steil" nor 
17   * the names of its contributors may be used to endorse 
18   * or promote products derived from this software without 
19   * specific prior written permission.
20   * 
21   * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT 
22   * HOLDERS AND CONTRIBUTORS "AS IS" AND ANY 
23   * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, 
24   * BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF 
25   * MERCHANTABILITY AND FITNESS FOR A PARTICULAR 
26   * PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL 
27   * THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE 
28   * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 
29   * EXEMPLARY, OR CONSEQUENTIAL DAMAGES 
30   * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 
31   * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, 
32   * OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER 
33   * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER 
34   * IN CONTRACT, STRICT LIABILITY, OR TORT 
35   * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN 
36   * ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF 
37   * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE
38   * 
39   * This file creating date: Feb 23, 2003 / 2:56:58 PM
40   * The JForum Project
41   * http://www.jforum.net
42   */
43  package net.jforum.dao;
44  
45  import java.util.Collection  ;
46  import java.util.List  ;
47  import java.util.Map  ;
48  
49  import net.jforum.entities.Topic;
50  
51  /**
52  * Model interface for {@link net.jforum.Topic}.
53   * This interface defines methods which are expected to be
54   * implementd by a specific data access driver. The intention is
55   * to provide all functionality needed to update, insert, delete and
56   * select some specific data.
57   *
58   * @author Rafael Steil
59   * @version $Id: TopicDAO.java,v 1.8 2005/09/12 21:05:24 rafaelsteil Exp $
60   */
61  public interface TopicDAO 
62  {
63      /**
64       * Fixes the fields <i>topic_first_post_id</i> and 
65       * <i>topic_last_post_id</i>.
66       * 
67       * @param topicId The topic id to fix
68       * @throws Exception
69       */
70      public void fixFirstLastPostId(int topicId) throws Exception  ;
71      
72      /**
73       * Gets a specific <code>Topic</code>.
74       * 
75       * @param topicId The Topic ID to search
76       * @return <code>Topic</code>object containing all the information
77       * @throws Exception
78       * @see #selectAll
79       */
80      public Topic selectById(int topicId) throws Exception  ;
81      
82      /**
83       * Gets a topic's information from the topics table only.
84       * No other information, like usernames, are fetched. 
85       * 
86       * @param topicId The topic id to get
87       * @return A topic instance
88       * @throws Exception
89       */
90      public Topic selectRaw(int topicId) throws Exception  ;
91      
92      /**
93       * Selects all topics associated to a specific forum
94       * 
95       * @param forumId The forum id to select the topics
96       * @return <code>ArrayList</code> with all topics found. Each entry is a <code>net.jforum.Topic</code> object
97       * @throws Exception
98       */
99      public List   selectAllByForum(int forumId) throws Exception  ;
100     
101     public List   selectTopicTitlesByIds(Collection   idList) throws Exception  ;
102     
103     /**
104      * Selects all topics associated to a specific forum, limiting the total number
105      * of records returned.
106      * 
107      * @param forumId The forum id to select the topics
108      * @return <code>ArrayList</code> with all topics found. Each entry is a <code>net.jforum.Topic</code> object
109      * @throws Exception
110      */
111     public List   selectAllByForumByLimit(int forumId, int startFrom, int count) throws Exception  ;
112 
113        /**
114      * Selects all topics associated to a specific user and belonging to 
115      * given forums
116      * @param userId User ID.
117      * @throws Exception
118      */
119     public List   selectByUserByLimit(int userId,int startFrom, int count) throws Exception  ;
120 
121     /**
122      * How many topics were created by a given user
123      * @param userId the user id to check
124      * @return the number of topics created by the user
125      * @throws Exception
126      */
127     public int countUserTopics(int userId) throws Exception  ;
128 
129     /**
130      * Selects the last <code>count</code> topics postted. 
131      * 
132      * @param count The desired total to retrieve
133      * @return <code>ArrayList</code> with all topics found. Each entry is a <code>net.jforum.Topic</code> object
134      * @throws Exception
135      */
136     public List   selectLastN(int count) throws Exception  ;
137     
138     /**
139      * Delete a Topic.
140      * 
141      * @param topicId The Topic ID to delete
142      * @return The total of related posts removed
143      * @throws Exception
144      * @see #canDelete(int)
145      */
146     public void delete(Topic topic) throws Exception  ;
147     
148     /**
149      * Deletes a set of topics
150      * @param topics The topics to delete. Each entry must be
151      * an instance of net.jforum.entities.Topic
152      * @throws Exception
153      */
154     public void deleteTopics(List   topics) throws Exception  ;
155     
156     /**
157      * Deletes all topics from a forum
158      * @param forumId
159      * @throws Exception
160      */
161     public void deleteByForum(int forumId) throws Exception  ;
162     
163     /**
164      * Updates a Topic.
165      * 
166      * @param topic Reference to a <code>Topic</code> object to update
167      * @throws Exception
168      * @see #update(int)
169      */
170     public void update(Topic topic) throws Exception  ;
171     
172     /**
173      * Adds a new Topic.
174      * 
175      * @param topic Reference to a valid and configured <code>Topic</code> object
176      * @return The new ID
177      * @throws Exception
178      */
179     public int addNew(Topic topic) throws Exception  ;
180     
181     /**
182      * Increments the number of times the topic was saw
183      * 
184      * @param topicId The topic ID to increment the total number of views
185      * @throws Exception
186      */
187     public void incrementTotalViews(int topicId) throws Exception  ;
188     
189     /**
190      * Increments the number of replies the topic has
191      * 
192      * @param topicId The topic ID to increment the total number of replies
193      * @throws Exception
194      */
195     public void incrementTotalReplies(int topicId) throws Exception  ;
196 
197     /**
198      * Decrements the number of replies the topic has
199      * 
200      * @param topicId The topic ID to decrement the total number of replies
201      * @throws Exception
202      */
203     public void decrementTotalReplies(int topicId) throws Exception  ;
204     
205     /**
206      * Sets the ID of the last post of the topic
207      * 
208      * @param topicId Topic ID
209      * @param postId Post ID
210      * @throws Exception
211      */
212     public void setLastPostId(int topicId, int postId) throws Exception  ;
213     
214     /**
215      * Gets the last post id associated to the topic
216      * 
217      * @param topicId The topic id
218      * @throws Exception
219      */
220     public int getMaxPostId(int topicId) throws Exception  ;
221     
222     /**
223      * Gets the number of posts the topic has.
224      * 
225      * @param topicId The topic id
226      * @return The number of posts
227      * @throws Exception
228      */
229     public int getTotalPosts(int topicId) throws Exception  ;
230     
231     /**
232      * Get the users to notify
233      * 
234      * @param topic The topic 
235      * @return <code>ArrayList</code> of <code>User</code> objects. Each
236      * entry is an user who will receive the topic anwser notification
237      * @throws Exception
238      * */
239     public List   notifyUsers(Topic topic) throws Exception  ;
240     
241     /**
242      * Subscribe the user for notification of new post on the topic
243      *  
244      * @param topicId The topic id
245      * @param userId The user id
246      * @throws Exception
247      */ 
248     public void subscribeUser(int topicId, int userId) throws Exception  ;
249     
250     /**
251      * Return the subscrition status of the user on the topic.
252      * 
253      * @param topicId The topic id
254      * @param userId The user id
255      * @return true if the user is waiting notification on the topic
256      * @throws Exception
257      */ 
258     public boolean isUserSubscribed(int topicId, int userId) throws Exception  ;
259     
260     /**
261      * Remove the user's subscription of the topic
262      * 
263      * @param topicId The topic id
264      * @param userId the User id
265      * @throws Exception
266      */
267     public void removeSubscription(int topicId, int userId) throws Exception  ;
268     
269     /**
270      * Clean all subscriptions of some topic
271      * 
272      * @param topicId The topic id
273      * @throws Exception
274      */
275     public void removeSubscriptionByTopic(int topicId) throws Exception  ;
276     
277     /**
278      * Change the topic read status 
279      * 
280      * @param topicId The topic id
281      * @param userId The user id
282      * @param read <code>true</code> or <code>false</code>
283      * @throws Exception
284      */
285     public void updateReadStatus(int topicId, int userId, boolean read) throws Exception  ;
286     
287     /**
288      * Lock or unlock a topic. 
289      * 
290      * @param topicId The topic id to perform the action on
291      * @param status Use <code>Topic.STATUS_LOCKED</code> to lock the topic, or
292      * <code>Topic.STATUS_UNLOCKED</code> to unlock. 
293      * @throws Exception
294      */
295     public void lockUnlock(int[] topicId, int status) throws Exception  ;
296 
297     /**
298      * Selects recent topics 
299      *
300      * @param limit The number of topics to retrieve
301      * @throws Exception
302      */ 
303     public List   selectRecentTopics (int limit) throws Exception  ;
304     
305     /**
306      * Sets the ID of the first post of the topic
307      * 
308      * @param topicId Topic ID
309      * @param postId Post ID
310      * @throws Exception
311      */
312     public void setFirstPostId(int topicId, int postId) throws Exception  ;
313 
314     /**
315      * Gets the first post id associated to the topic
316      * 
317      * @param topicId The topic id
318      * @throws Exception
319      */
320     public int getMinPostId(int topicId) throws Exception  ;
321     
322     /**
323      * Sets the moderatation flag for all topics of a given forum.
324      * 
325      * @param forumId The forum id
326      * @param status
327      * @throws Exception
328      */
329     public void setModerationStatus(int forumId, boolean status) throws Exception  ;
330 
331     /**
332      * Sets the moderatation flag for a given topic.
333      * 
334      * @param forumId The topic id
335      * @param status
336      * @throws Exception
337      */
338     public void setModerationStatusByTopic(int topicId, boolean status) throws Exception  ;
339 
340     /**
341      * Get all unique posters of some topic
342      * @param topicId
343      * @return A Map instance with all topic posts. Key is the userid, 
344      * value is an {@link net.jforum.entities.User} instance with minimum
345      * data filled
346      * @throws Exception
347      */
348     public Map   topicPosters(int topicId) throws Exception  ;
349 }
350
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags