Fetcher


1   /**
2    * Copyright (c) 2003-2006, David A. Czarnecki
3    * All rights reserved.
4    *
5    * Redistribution and use in source and binary forms, with or without
6    * modification, are permitted provided that the following conditions are met:
7    *
8    * Redistributions of source code must retain the above copyright notice, this list of conditions and the
9    *     following disclaimer.
10   * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the
11   *     following disclaimer in the documentation and/or other materials provided with the distribution.
12   * Neither the name of "David A. Czarnecki" and "blojsom" nor the names of its contributors may be used to
13   *     endorse or promote products derived from this software without specific prior written permission.
14   * Products derived from this software may not be called "blojsom", nor may "blojsom" appear in their name,
15   *     without prior written permission of David A. Czarnecki.
16   *
17   * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
18   * CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
19   * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
20   * AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO
21   * EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
22   * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
23   * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
24   * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
25   * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
26   * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
27   * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
28   * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
29   * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
30   */
31  package org.blojsom.fetcher;
32  
33  import org.blojsom.blog.*;
34  
35  import javax.servlet.http.HttpServletRequest  ;
36  import javax.servlet.http.HttpServletResponse  ;
37  import java.util.Map  ;
38  import java.util.List  ;
39  import java.util.Date  ;
40  
41  /**
42   * Fetcher
43   *
44   * @author David Czarnecki
45   * @since blojsom 3.0
46   * @version $Id: Fetcher.java,v 1.17 2006/05/12 15:09:54 czarneckid Exp $
47   */
48  public interface Fetcher {
49  
50      /**
51       * Initialize this fetcher. This method only called when the fetcher is instantiated.
52       *
53       * @throws FetcherException If there is an error initializing the fetcher
54       */
55      public void init() throws FetcherException;
56  
57      /**
58       * Return a new {@link Entry} instance
59       *
60       * @return Blog entry instance
61       */
62      public Entry newEntry();
63  
64      /**
65       * Return a new {@link Comment} instance
66       *
67       * @return {@link Comment}
68       */
69      public Comment newComment();
70  
71      /**
72       * Return a new {@link Trackback} instance
73       *
74       * @return {@link Trackback}
75       */
76      public Trackback newTrackback();
77  
78      /**
79       * Return a new {@link Pingback} instance
80       *
81       * @return {@link Pingback}
82       */
83      public Pingback newPingback();
84  
85      /**
86       * Return a new {@link Category} instance
87       *
88       * @return {@link Category}
89       */
90      public Category newCategory();
91  
92      /**
93       * Return a new {@link Blog} instance
94       *
95       * @return {@link Blog}
96       */
97      public Blog newBlog();
98  
99      /**
100      * Return a new {@link User} instance
101      *
102      * @return {@link User}
103      */
104     public User newUser();
105 
106     /**
107      * Load the blog IDs
108      *
109      * @return List of blog IDs
110      * @throws FetcherException If there is an error loading the blog IDs
111      */
112     public String  [] loadBlogIDs() throws FetcherException;
113 
114     /**
115      * Load the {@link Blog} given the blog ID
116      *
117      * @param blogId Blog ID
118      * @return {@link Blog}
119      * @throws FetcherException If there is an error loading the blog
120      */
121     public Blog loadBlog(String   blogId) throws FetcherException;
122 
123     /**
124      * Save a {@link Blog}
125      *
126      * @param blog {@link Blog}
127      * @throws FetcherException If there is an error saving the blog
128      */
129     public void saveBlog(Blog blog) throws FetcherException;
130 
131     /**
132      * Delete a blog
133      *
134      * @param blog {@link Blog}
135      * @throws FetcherException If there is an error deleting the blog
136      */
137     public void deleteBlog(Blog blog) throws FetcherException;
138 
139     /**
140      * Fetch a set of {@link Entry} objects.
141      *
142      * @param httpServletRequest Request
143      * @param httpServletResponse Response
144      * @param blog {@link Blog} instance
145      * @param flavor Flavor
146      * @param context Context
147      * @return Blog entries retrieved for the particular request
148      * @throws FetcherException If there is an error retrieving the blog entries for the request
149      */
150     public Entry[] fetchEntries(HttpServletRequest   httpServletRequest,
151                                 HttpServletResponse   httpServletResponse,
152                                 Blog blog,
153                                 String   flavor,
154                                 Map   context) throws FetcherException;
155 
156     /**
157      * Load all the entries for a given category
158      *
159      * @param blog {@link Blog}
160      * @param categoryId Category ID
161      * @return Blog entries for a given category
162      * @throws FetcherException If there is an error loading the entries
163      */
164     public Entry[] loadAllEntriesForCategory(Blog blog, Integer   categoryId) throws FetcherException;
165 
166     /**
167      * Load all the entries for a given category
168      *
169      * @param blog {@link Blog}
170      * @param categoryId Category ID
171      * @param limit Limit on number of entries to return
172      * @return Blog entries for a given category
173      * @throws FetcherException If there is an error loading the entries
174      */
175     public Entry[] loadEntriesForCategory(Blog blog, Integer   categoryId, Integer   limit) throws FetcherException;
176 
177     /**
178      * Load a set of entries using a given page size and page in which to retrieve the entries
179      *
180      * @param blog {@link Blog}
181      * @param pageSize Page size
182      * @param page Page
183      * @return Blog entries
184      * @throws FetcherException If there is an error loading the entries
185      */
186     public Entry[] loadEntries(Blog blog, int pageSize, int page) throws FetcherException;
187 
188     /**
189      * Find entries which have the search query in their title or description
190      *
191      * @param blog {@link Blog}
192      * @param query Search query
193      * @return Blog entries which have the search query in their title or descirption
194      * @throws FetcherException If there is an error searching through entries
195      */
196     public Entry[] findEntries(Blog blog, String   query) throws FetcherException;
197 
198     /**
199      * Find entries by a metadata key/value pair
200      *
201      * @param blog {@link Blog}
202      * @param metadataKey Metadata key
203      * @param metadataValue Metadata value
204      * @param pre If the search should use % before the metadata value (match anything before)
205      * @param post If the search should use % after the metadata value (match antthing after)
206      * @return Entries matching metadata key and value using LIKE syntax for metadata value
207      * @throws FetcherException If there is an error searching through entries
208      */
209     public Entry[] findEntriesByMetadataKeyValue(Blog blog, String   metadataKey, String   metadataValue,
210                                                  boolean pre, boolean post) throws FetcherException;
211 
212     /**
213      * Find entries with a given metadata key
214      *
215      * @param blog {@link Blog}
216      * @param metadataKey Metadata key
217      * @return Entries with the given metadata key
218      * @throws FetcherException If there is an error searching through entries
219      */
220     public Entry[] findEntriesWithMetadataKey(Blog blog, String   metadataKey) throws FetcherException;
221 
222     /**
223      * Find entries between a start and end date
224      *
225      * @param blog {@link Blog}
226      * @param startDate Start date
227      * @param endDate End date
228      * @return Entries between a start and end date
229      * @throws FetcherException If there is an error searching for entries between the dates
230      */
231     public Entry[] findEntriesBetweenDates(Blog blog, Date   startDate, Date   endDate) throws FetcherException;
232 
233     /**
234      * Count the number of entries for a blog
235      *
236      * @param blog {@link Blog}
237      * @return Number of entries
238      * @throws FetcherException If there is an error counting the blog entries
239      */
240     public Integer   countEntries(Blog blog) throws FetcherException;
241 
242     /**
243      * Load an {@link Entry} for a given entry ID
244      *
245      * @param blog {@link Blog}
246      * @param entryId Entry ID
247      * @return {@link Entry}
248      * @throws FetcherException If there is an error loading the entry
249      */
250     public Entry loadEntry(Blog blog, Integer   entryId) throws FetcherException;
251 
252     /**
253      * Load an {@link Entry} given a post slug
254      *
255      * @param blog {@link Blog}
256      * @param postSlug Post slug
257      * @return {@link Entry} for the given post slug
258      * @throws FetcherException If an entry for the blog and post slug cannot be found
259      */
260     public Entry loadEntry(Blog blog, String   postSlug) throws FetcherException;
261 
262     /**
263      * Fetch a set of {@link Category} objects
264      *
265      * @param httpServletRequest Request
266      * @param httpServletResponse Response
267      * @param blog {@link Blog} instance
268      * @param flavor Flavor
269      * @param context Context
270      * @return Blog categories retrieved for the particular request
271      * @throws FetcherException If there is an error retrieving the blog categories for the request
272      */
273     public Category[] fetchCategories(HttpServletRequest   httpServletRequest,
274                                       HttpServletResponse   httpServletResponse,
275                                       Blog blog,
276                                       String   flavor,
277                                       Map   context) throws FetcherException;
278 
279     /**
280      * Load each {@link Category} for a given blog
281      *
282      * @param blog {@link Blog}
283      * @return {@link Category} list for the blog
284      * @throws FetcherException If there is an error loading the categories
285      */
286     public Category[] loadAllCategories(Blog blog) throws FetcherException;
287 
288     /**
289      * Load the {@link Category} for a given category ID
290      *
291      * @param blog {@link Blog}
292      * @param categoryId Category ID
293      * @return {@link Category} for the given category ID
294      * @throws FetcherException If there is an error loading the category
295      */
296     public Category loadCategory(Blog blog, Integer   categoryId) throws FetcherException;
297 
298     /**
299      * Load the {@link Category} for a given category name
300      *
301      * @param blog {@link Blog}
302      * @param name Category name
303      * @return {@link Category} for the given category name
304      * @throws FetcherException If there is an error loading the category
305      */
306     public Category loadCategory(Blog blog, String   name) throws FetcherException;
307 
308     /**
309      * Save a given {@link Entry}
310      *
311      * @param blog {@link Blog}
312      * @param entry {@link Entry} to save
313      * @throws FetcherException If there is an error saving the entry
314      */
315     public void saveEntry(Blog blog, Entry entry) throws FetcherException;
316 
317     /**
318      * Load a given {@link Entry}
319      *
320      * @param blog {@link Blog}
321      * @param entry {@link Entry} to load
322      * @throws FetcherException If there is an error loading the entry
323      */
324     public void loadEntry(Blog blog, Entry entry) throws FetcherException;
325 
326     /**
327      * Delete a given {@link Entry}
328      *
329      * @param blog {@link Blog}
330      * @param entry {@link Entry} to delete
331      * @throws FetcherException If there is an error deleting the entry
332      */
333     public void deleteEntry(Blog blog, Entry entry) throws FetcherException;
334 
335     /**
336      * Save a given {@link Category}
337      *
338      * @param blog {@link Blog}
339      * @param category {@link Category} to save
340      * @throws FetcherException If there is an error saving the category
341      */
342     public void saveCategory(Blog blog, Category category) throws FetcherException;
343 
344     /**
345      * Load a given {@link Category}
346      *
347      * @param blog {@link Blog}
348      * @param category {@link Category} to load
349      * @throws FetcherException If there is an loading saving the category
350      */
351     public void loadCategory(Blog blog, Category category) throws FetcherException;
352 
353     /**
354      * Delete a given {@link Category}
355      *
356      * @param blog {@link Blog}
357      * @param category {@link Category} to delete
358      * @throws FetcherException If there is an error deleting the category
359      */
360     public void deleteCategory(Blog blog, Category category) throws FetcherException;
361 
362     /**
363      * Save a given {@link Comment}
364      *
365      * @param blog {@link Blog}
366      * @param comment {@link Comment} to save
367      * @throws FetcherException If there is an error saving the comment
368      */
369     public void saveComment(Blog blog, Comment comment) throws FetcherException;
370 
371     /**
372      * Load a given {@link Comment}
373      *
374      * @param blog {@link Blog}
375      * @param comment {@link Comment} to load
376      * @throws FetcherException If there is an error loading the comment
377      */
378     public void loadComment(Blog blog, Comment comment) throws FetcherException;
379 
380     /**
381      * Delete a given {@link Comment}
382      *
383      * @param blog {@link Blog}
384      * @param comment {@link Comment} to delete
385      * @throws FetcherException If there is an error deleting the comment
386      */
387     public void deleteComment(Blog blog, Comment comment) throws FetcherException;
388 
389     /**
390      * Load the recent comments for a blog
391      *
392      * @param blog {@link Blog}
393      * @throws FetcherException If there is an error retrieving the recent comments
394      */
395     public List   loadRecentComments(Blog blog) throws FetcherException;
396 
397     /**
398      * Save a given {@link Trackback}
399      *
400      * @param blog {@link Blog}
401      * @param trackback {@link Trackback} to save
402      * @throws FetcherException If there is an error saving the trackback
403      */
404     public void saveTrackback(Blog blog, Trackback trackback) throws FetcherException;
405 
406     /**
407      * Load a given {@link Trackback}
408      *
409      * @param blog {@link Blog}
410      * @param trackback {@link Trackback} to load
411      * @throws FetcherException If there is an error loading the trackback
412      */
413     public void loadTrackback(Blog blog, Trackback trackback) throws FetcherException;
414 
415     /**
416      * Delete a given {@link Trackback}
417      *
418      * @param blog {@link Blog}
419      * @param trackback {@link Trackback} to delete
420      * @throws FetcherException If there is an error deleting the trackback
421      */
422     public void deleteTrackback(Blog blog, Trackback trackback) throws FetcherException;
423 
424     /**
425      * Load the recent trackbacks for a blog
426      *
427      * @param blog {@link Blog}
428      * @throws FetcherException If there is an error retrieving the recent trackbacks
429      */
430     public List   loadRecentTrackbacks(Blog blog) throws FetcherException;
431 
432     /**
433      * Save a given {@link Pingback}
434      *
435      * @param blog {@link Blog}
436      * @param pingback {@link Pingback} to save
437      * @throws FetcherException If there is an error saving the pingback
438      */
439     public void savePingback(Blog blog, Pingback pingback) throws FetcherException;
440 
441     /**
442      * Load a given {@link Pingback}
443      *
444      * @param blog {@link Blog}
445      * @param pingback {@link Pingback} to load
446      * @throws FetcherException If there is an error loading the pingback
447      */
448     public void loadPingback(Blog blog, Pingback pingback) throws FetcherException;
449 
450     /**
451      * Load a pingback given the source URI and target URI
452      *
453      * @param blog {@link Blog}
454      * @param sourceURI Source URI
455      * @param targetURI Target URI
456      * @return {@link Pingback} given the source and target URIs or <code>null</code> if not found
457      * @throws FetcherException If there was an erorr loading the pingback
458      */
459     public Pingback loadPingback(Blog blog, String   sourceURI, String   targetURI) throws FetcherException;
460 
461     /**
462      * Delete a given {@link Pingback}
463      *
464      * @param blog {@link Blog}
465      * @param pingback {@link Pingback} to delete
466      * @throws FetcherException If there is an error deleting the pingback
467      */
468     public void deletePingback(Blog blog, Pingback pingback) throws FetcherException;
469 
470     /**
471      * Load the recent pingbacks for a blog
472      *
473      * @param blog {@link Blog}
474      * @throws FetcherException If there is an error retrieving the recent pingbacks
475      */
476     public List   loadRecentPingbacks(Blog blog) throws FetcherException;
477 
478     /**
479      * Retrieve the users for a given blog
480      *
481      * @param blog {@link Blog}
482      * @return List of {@link User}s for a blog
483      */
484     public User[] getUsers(Blog blog);
485 
486     /**
487      * Load a {@link User} from a blog
488      *
489      * @param blog      {@link Blog}
490      * @param userLogin Login ID
491      * @throws FetcherException If there is an error loading the {@link User} from the blog
492      */
493     public User loadUser(Blog blog, String   userLogin) throws FetcherException;
494 
495     /**
496      * Load a given {@link User} from a blog given their ID
497      *
498      * @param blog {@link Blog}
499      * @param userID User ID
500      * @return {@link User}
501      * @throws FetcherException If there is an error loading the user
502      */
503     public User loadUser(Blog blog, Integer   userID) throws FetcherException;
504 
505     /**
506      * Save a given {@link User} to the blog
507      *
508      * @param blog {@link Blog}
509      * @param user {@link User}
510      * @return {@link User}
511      * @throws FetcherException If there is an error saving the user to the blog
512      */
513     public User saveUser(Blog blog, User user) throws FetcherException;
514 
515     /**
516      * Delete a given user from a blog
517      *
518      * @param blog {@link Blog}
519      * @param userID User ID
520      * @throws FetcherException If there is an error deleting the user from the blog
521      */
522     public void deleteUser(Blog blog, Integer   userID) throws FetcherException;
523 
524     /**
525      * Find the responses (comments, trackbacks, pingbacks) for a given {@link Blog} matching one of a set of status codes
526      *
527      * @param blog {@link Blog}
528      * @param status List of status codes to search
529      * @return List of responses (comments, trackbacks, pingbacks) matching one of a set of status codes
530      * @throws FetcherException If there is an error loading the responses
531      */
532     public List   findResponsesByStatus(Blog blog, String  [] status) throws FetcherException;
533 
534     /**
535      * Find the responses (comments, trackbacks, pingbacks) for a given {@link Blog} matching some query
536      *
537      * @param blog {@link Blog}
538      * @param query Query which will match on various items such as commenter name, e-mail, IP address, etc.
539      * @return List of responses (comments, trackbacks, pingbacks) matching query
540      * @throws FetcherException If there is an error loading the responses
541      */
542     public List   findResponsesByQuery(Blog blog, String   query) throws FetcherException;
543 
544     /**
545      * Called when {@link org.blojsom.servlet.BlojsomServlet} is taken out of service
546      *
547      * @throws FetcherException If there is an error in finalizing this fetcher
548      */
549     public void destroy() throws FetcherException;
550 }
551
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags