001: /**
002: * Copyright (c) 2003-2007, David A. Czarnecki
003: * All rights reserved.
004: *
005: * Redistribution and use in source and binary forms, with or without
006: * modification, are permitted provided that the following conditions are met:
007: *
008: * Redistributions of source code must retain the above copyright notice, this list of conditions and the
009: * following disclaimer.
010: * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the
011: * following disclaimer in the documentation and/or other materials provided with the distribution.
012: * Neither the name of "David A. Czarnecki" and "blojsom" nor the names of its contributors may be used to
013: * endorse or promote products derived from this software without specific prior written permission.
014: * Products derived from this software may not be called "blojsom", nor may "blojsom" appear in their name,
015: * without prior written permission of David A. Czarnecki.
016: *
017: * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND
018: * CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
019: * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
020: * AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO
021: * EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
022: * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
023: * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
024: * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
025: * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED
026: * AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
027: * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
028: * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
029: * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
030: */package org.blojsom.fetcher;
031:
032: import org.blojsom.blog.*;
033:
034: import javax.servlet.http.HttpServletRequest;
035: import javax.servlet.http.HttpServletResponse;
036: import java.util.Map;
037: import java.util.List;
038: import java.util.Date;
039:
040: /**
041: * Fetcher
042: *
043: * @author David Czarnecki
044: * @since blojsom 3.0
045: * @version $Id: Fetcher.java,v 1.20 2007/01/17 02:35:17 czarneckid Exp $
046: */
047: public interface Fetcher {
048:
049: /**
050: * Initialize this fetcher. This method only called when the fetcher is instantiated.
051: *
052: * @throws FetcherException If there is an error initializing the fetcher
053: */
054: public void init() throws FetcherException;
055:
056: /**
057: * Return a new {@link Entry} instance
058: *
059: * @return Blog entry instance
060: */
061: public Entry newEntry();
062:
063: /**
064: * Return a new {@link Comment} instance
065: *
066: * @return {@link Comment} comment
067: */
068: public Comment newComment();
069:
070: /**
071: * Return a new {@link Trackback} instance
072: *
073: * @return {@link Trackback} trackback
074: */
075: public Trackback newTrackback();
076:
077: /**
078: * Return a new {@link Pingback} instance
079: *
080: * @return {@link Pingback} pingback
081: */
082: public Pingback newPingback();
083:
084: /**
085: * Return a new {@link Category} instance
086: *
087: * @return {@link Category} category
088: */
089: public Category newCategory();
090:
091: /**
092: * Return a new {@link Blog} instance
093: *
094: * @return {@link Blog} blog
095: */
096: public Blog newBlog();
097:
098: /**
099: * Return a new {@link User} instance
100: *
101: * @return {@link User} user
102: */
103: public User newUser();
104:
105: /**
106: * Load the blog IDs
107: *
108: * @return List of blog IDs
109: * @throws FetcherException If there is an error loading the blog IDs
110: */
111: public String[] loadBlogIDs() throws FetcherException;
112:
113: /**
114: * Load the {@link Blog} given the blog ID
115: *
116: * @param blogId Blog ID
117: * @return {@link Blog} blog
118: * @throws FetcherException If there is an error loading the blog
119: */
120: public Blog loadBlog(String blogId) throws FetcherException;
121:
122: /**
123: * Load the {@link Blog} given the ID
124: *
125: * @param id ID
126: * @return {@link Blog} blog
127: * @throws FetcherException If there is an error loading the blog
128: */
129: public Blog loadBlog(Integer id) throws FetcherException;
130:
131: /**
132: * Save a {@link Blog}
133: *
134: * @param blog {@link Blog}
135: * @throws FetcherException If there is an error saving the blog
136: */
137: public void saveBlog(Blog blog) throws FetcherException;
138:
139: /**
140: * Delete a blog
141: *
142: * @param blog {@link Blog}
143: * @throws FetcherException If there is an error deleting the blog
144: */
145: public void deleteBlog(Blog blog) throws FetcherException;
146:
147: /**
148: * Fetch a set of {@link Entry} objects.
149: *
150: * @param httpServletRequest Request
151: * @param httpServletResponse Response
152: * @param blog {@link Blog} instance
153: * @param flavor Flavor
154: * @param context Context
155: * @return Blog entries retrieved for the particular request
156: * @throws FetcherException If there is an error retrieving the blog entries for the request
157: */
158: public Entry[] fetchEntries(HttpServletRequest httpServletRequest,
159: HttpServletResponse httpServletResponse, Blog blog,
160: String flavor, Map context) throws FetcherException;
161:
162: /**
163: * Load all the entries for a given category
164: *
165: * @param blog {@link Blog}
166: * @param categoryId Category ID
167: * @return Blog entries for a given category
168: * @throws FetcherException If there is an error loading the entries
169: */
170: public Entry[] loadAllEntriesForCategory(Blog blog,
171: Integer categoryId) throws FetcherException;
172:
173: /**
174: * Load all the entries for a given category
175: *
176: * @param blog {@link Blog}
177: * @param categoryId Category ID
178: * @param limit Limit on number of entries to return
179: * @return Blog entries for a given category
180: * @throws FetcherException If there is an error loading the entries
181: */
182: public Entry[] loadEntriesForCategory(Blog blog,
183: Integer categoryId, Integer limit) throws FetcherException;
184:
185: /**
186: * Load a set of entries using a given page size and page in which to retrieve the entries
187: *
188: * @param blog {@link Blog}
189: * @param pageSize Page size
190: * @param page Page
191: * @return Blog entries
192: * @throws FetcherException If there is an error loading the entries
193: */
194: public Entry[] loadEntries(Blog blog, int pageSize, int page)
195: throws FetcherException;
196:
197: /**
198: * Load a set of entries using a given page size and page in which to retrieve the entries
199: *
200: * @param pageSize Page size
201: * @param page Page
202: * @param specificCategory Category
203: * @param defaultCategories Default categories to use for requesting entries from the blogs
204: * @return Blog entries
205: * @throws FetcherException If there is an error loading the entries
206: */
207: public Entry[] loadEntries(int pageSize, int page,
208: Category specificCategory, Category[] defaultCategories)
209: throws FetcherException;
210:
211: /**
212: * Find entries which have the search query in their title or description
213: *
214: * @param blog {@link Blog}
215: * @param query Search query
216: * @return Blog entries which have the search query in their title or descirption
217: * @throws FetcherException If there is an error searching through entries
218: */
219: public Entry[] findEntries(Blog blog, String query)
220: throws FetcherException;
221:
222: /**
223: * Find entries by a metadata key/value pair
224: *
225: * @param blog {@link Blog}
226: * @param metadataKey Metadata key
227: * @param metadataValue Metadata value
228: * @param pre If the search should use % before the metadata value (match anything before)
229: * @param post If the search should use % after the metadata value (match antthing after)
230: * @return Entries matching metadata key and value using LIKE syntax for metadata value
231: * @throws FetcherException If there is an error searching through entries
232: */
233: public Entry[] findEntriesByMetadataKeyValue(Blog blog,
234: String metadataKey, String metadataValue, boolean pre,
235: boolean post) throws FetcherException;
236:
237: /**
238: * Find entries with a given metadata key
239: *
240: * @param blog {@link Blog}
241: * @param metadataKey Metadata key
242: * @return Entries with the given metadata key
243: * @throws FetcherException If there is an error searching through entries
244: */
245: public Entry[] findEntriesWithMetadataKey(Blog blog,
246: String metadataKey) throws FetcherException;
247:
248: /**
249: * Find entries between a start and end date
250: *
251: * @param blog {@link Blog}
252: * @param startDate Start date
253: * @param endDate End date
254: * @return Entries between a start and end date
255: * @throws FetcherException If there is an error searching for entries between the dates
256: */
257: public Entry[] findEntriesBetweenDates(Blog blog, Date startDate,
258: Date endDate) throws FetcherException;
259:
260: /**
261: * Count the number of entries for a blog
262: *
263: * @param blog {@link Blog}
264: * @return Number of entries
265: * @throws FetcherException If there is an error counting the blog entries
266: */
267: public Integer countEntries(Blog blog) throws FetcherException;
268:
269: /**
270: * Load an {@link Entry} for a given entry ID
271: *
272: * @param blog {@link Blog}
273: * @param entryId Entry ID
274: * @return {@link Entry} entry
275: * @throws FetcherException If there is an error loading the entry
276: */
277: public Entry loadEntry(Blog blog, Integer entryId)
278: throws FetcherException;
279:
280: /**
281: * Load an {@link Entry} given a post slug
282: *
283: * @param blog {@link Blog}
284: * @param postSlug Post slug
285: * @return {@link Entry} for the given post slug
286: * @throws FetcherException If an entry for the blog and post slug cannot be found
287: */
288: public Entry loadEntry(Blog blog, String postSlug)
289: throws FetcherException;
290:
291: /**
292: * Fetch a set of {@link Category} objects
293: *
294: * @param httpServletRequest Request
295: * @param httpServletResponse Response
296: * @param blog {@link Blog} instance
297: * @param flavor Flavor
298: * @param context Context
299: * @return Blog categories retrieved for the particular request
300: * @throws FetcherException If there is an error retrieving the blog categories for the request
301: */
302: public Category[] fetchCategories(
303: HttpServletRequest httpServletRequest,
304: HttpServletResponse httpServletResponse, Blog blog,
305: String flavor, Map context) throws FetcherException;
306:
307: /**
308: * Load each {@link Category} for a given blog
309: *
310: * @param blog {@link Blog}
311: * @return {@link Category} list for the blog
312: * @throws FetcherException If there is an error loading the categories
313: */
314: public Category[] loadAllCategories(Blog blog)
315: throws FetcherException;
316:
317: /**
318: * Load the {@link Category} for a given category ID
319: *
320: * @param blog {@link Blog}
321: * @param categoryId Category ID
322: * @return {@link Category} for the given category ID
323: * @throws FetcherException If there is an error loading the category
324: */
325: public Category loadCategory(Blog blog, Integer categoryId)
326: throws FetcherException;
327:
328: /**
329: * Load the {@link Category} for a given category name
330: *
331: * @param blog {@link Blog}
332: * @param name Category name
333: * @return {@link Category} for the given category name
334: * @throws FetcherException If there is an error loading the category
335: */
336: public Category loadCategory(Blog blog, String name)
337: throws FetcherException;
338:
339: /**
340: * Save a given {@link Entry}
341: *
342: * @param blog {@link Blog}
343: * @param entry {@link Entry} to save
344: * @throws FetcherException If there is an error saving the entry
345: */
346: public void saveEntry(Blog blog, Entry entry)
347: throws FetcherException;
348:
349: /**
350: * Load a given {@link Entry}
351: *
352: * @param blog {@link Blog}
353: * @param entry {@link Entry} to load
354: * @throws FetcherException If there is an error loading the entry
355: */
356: public void loadEntry(Blog blog, Entry entry)
357: throws FetcherException;
358:
359: /**
360: * Delete a given {@link Entry}
361: *
362: * @param blog {@link Blog}
363: * @param entry {@link Entry} to delete
364: * @throws FetcherException If there is an error deleting the entry
365: */
366: public void deleteEntry(Blog blog, Entry entry)
367: throws FetcherException;
368:
369: /**
370: * Save a given {@link Category}
371: *
372: * @param blog {@link Blog}
373: * @param category {@link Category} to save
374: * @throws FetcherException If there is an error saving the category
375: */
376: public void saveCategory(Blog blog, Category category)
377: throws FetcherException;
378:
379: /**
380: * Load a given {@link Category}
381: *
382: * @param blog {@link Blog}
383: * @param category {@link Category} to load
384: * @throws FetcherException If there is an loading saving the category
385: */
386: public void loadCategory(Blog blog, Category category)
387: throws FetcherException;
388:
389: /**
390: * Delete a given {@link Category}
391: *
392: * @param blog {@link Blog}
393: * @param category {@link Category} to delete
394: * @throws FetcherException If there is an error deleting the category
395: */
396: public void deleteCategory(Blog blog, Category category)
397: throws FetcherException;
398:
399: /**
400: * Save a given {@link Comment}
401: *
402: * @param blog {@link Blog}
403: * @param comment {@link Comment} to save
404: * @throws FetcherException If there is an error saving the comment
405: */
406: public void saveComment(Blog blog, Comment comment)
407: throws FetcherException;
408:
409: /**
410: * Load a given {@link Comment}
411: *
412: * @param blog {@link Blog}
413: * @param comment {@link Comment} to load
414: * @throws FetcherException If there is an error loading the comment
415: */
416: public void loadComment(Blog blog, Comment comment)
417: throws FetcherException;
418:
419: /**
420: * Delete a given {@link Comment}
421: *
422: * @param blog {@link Blog}
423: * @param comment {@link Comment} to delete
424: * @throws FetcherException If there is an error deleting the comment
425: */
426: public void deleteComment(Blog blog, Comment comment)
427: throws FetcherException;
428:
429: /**
430: * Load the recent comments for a blog
431: *
432: * @param blog {@link Blog}
433: * @return List of recent comment
434: * @throws FetcherException If there is an error retrieving the recent comments
435: */
436: public List loadRecentComments(Blog blog) throws FetcherException;
437:
438: /**
439: * Save a given {@link Trackback}
440: *
441: * @param blog {@link Blog}
442: * @param trackback {@link Trackback} to save
443: * @throws FetcherException If there is an error saving the trackback
444: */
445: public void saveTrackback(Blog blog, Trackback trackback)
446: throws FetcherException;
447:
448: /**
449: * Load a given {@link Trackback}
450: *
451: * @param blog {@link Blog}
452: * @param trackback {@link Trackback} to load
453: * @throws FetcherException If there is an error loading the trackback
454: */
455: public void loadTrackback(Blog blog, Trackback trackback)
456: throws FetcherException;
457:
458: /**
459: * Delete a given {@link Trackback}
460: *
461: * @param blog {@link Blog}
462: * @param trackback {@link Trackback} to delete
463: * @throws FetcherException If there is an error deleting the trackback
464: */
465: public void deleteTrackback(Blog blog, Trackback trackback)
466: throws FetcherException;
467:
468: /**
469: * Load the recent trackbacks for a blog
470: *
471: * @param blog {@link Blog}
472: * @return List of recent trackbacks
473: * @throws FetcherException If there is an error retrieving the recent trackbacks
474: */
475: public List loadRecentTrackbacks(Blog blog) throws FetcherException;
476:
477: /**
478: * Save a given {@link Pingback}
479: *
480: * @param blog {@link Blog}
481: * @param pingback {@link Pingback} to save
482: * @throws FetcherException If there is an error saving the pingback
483: */
484: public void savePingback(Blog blog, Pingback pingback)
485: throws FetcherException;
486:
487: /**
488: * Load a given {@link Pingback}
489: *
490: * @param blog {@link Blog}
491: * @param pingback {@link Pingback} to load
492: * @throws FetcherException If there is an error loading the pingback
493: */
494: public void loadPingback(Blog blog, Pingback pingback)
495: throws FetcherException;
496:
497: /**
498: * Load a pingback given the source URI and target URI
499: *
500: * @param blog {@link Blog}
501: * @param sourceURI Source URI
502: * @param targetURI Target URI
503: * @return {@link Pingback} given the source and target URIs or <code>null</code> if not found
504: * @throws FetcherException If there was an erorr loading the pingback
505: */
506: public Pingback loadPingback(Blog blog, String sourceURI,
507: String targetURI) throws FetcherException;
508:
509: /**
510: * Delete a given {@link Pingback}
511: *
512: * @param blog {@link Blog}
513: * @param pingback {@link Pingback} to delete
514: * @throws FetcherException If there is an error deleting the pingback
515: */
516: public void deletePingback(Blog blog, Pingback pingback)
517: throws FetcherException;
518:
519: /**
520: * Load the recent pingbacks for a blog
521: *
522: * @param blog {@link Blog}
523: * @return List of recent pingbacks
524: * @throws FetcherException If there is an error retrieving the recent pingbacks
525: */
526: public List loadRecentPingbacks(Blog blog) throws FetcherException;
527:
528: /**
529: * Retrieve the users for a given blog
530: *
531: * @param blog {@link Blog}
532: * @return List of {@link User}s for a blog
533: */
534: public User[] getUsers(Blog blog);
535:
536: /**
537: * Load a {@link User} from a blog
538: *
539: * @param blog {@link Blog}
540: * @param userLogin Login ID
541: * @return {@link User} user
542: * @throws FetcherException If there is an error loading the {@link User} from the blog
543: */
544: public User loadUser(Blog blog, String userLogin)
545: throws FetcherException;
546:
547: /**
548: * Load a given {@link User} from a blog given their ID
549: *
550: * @param blog {@link Blog}
551: * @param userID User ID
552: * @return {@link User} user
553: * @throws FetcherException If there is an error loading the user
554: */
555: public User loadUser(Blog blog, Integer userID)
556: throws FetcherException;
557:
558: /**
559: * Save a given {@link User} to the blog
560: *
561: * @param blog {@link Blog}
562: * @param user {@link User}
563: * @return {@link User} user
564: * @throws FetcherException If there is an error saving the user to the blog
565: */
566: public User saveUser(Blog blog, User user) throws FetcherException;
567:
568: /**
569: * Delete a given user from a blog
570: *
571: * @param blog {@link Blog}
572: * @param userID User ID
573: * @throws FetcherException If there is an error deleting the user from the blog
574: */
575: public void deleteUser(Blog blog, Integer userID)
576: throws FetcherException;
577:
578: /**
579: * Find the responses (comments, trackbacks, pingbacks) for a given {@link Blog} matching one of a set of status codes
580: *
581: * @param blog {@link Blog}
582: * @param status List of status codes to search
583: * @return List of responses (comments, trackbacks, pingbacks) matching one of a set of status codes
584: * @throws FetcherException If there is an error loading the responses
585: */
586: public List findResponsesByStatus(Blog blog, String[] status)
587: throws FetcherException;
588:
589: /**
590: * Find the responses (comments, trackbacks, pingbacks) for a given {@link Blog} matching some query
591: *
592: * @param blog {@link Blog}
593: * @param query Query which will match on various items such as commenter name, e-mail, IP address, etc.
594: * @return List of responses (comments, trackbacks, pingbacks) matching query
595: * @throws FetcherException If there is an error loading the responses
596: */
597: public List findResponsesByQuery(Blog blog, String query)
598: throws FetcherException;
599:
600: /**
601: * Called when {@link org.blojsom.servlet.BlojsomServlet} is taken out of service
602: *
603: * @throws FetcherException If there is an error in finalizing this fetcher
604: */
605: public void destroy() throws FetcherException;
606: }
|