001: /*
002: * Licensed to the Apache Software Foundation (ASF) under one or more
003: * contributor license agreements. The ASF licenses this file to You
004: * under the Apache License, Version 2.0 (the "License"); you may not
005: * use this file except in compliance with the License.
006: * You may obtain a copy of the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS,
012: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013: * See the License for the specific language governing permissions and
014: * limitations under the License. For additional information regarding
015: * copyright in this work, please see the NOTICE file in the top level
016: * directory of this distribution.
017: */
018:
019: package org.apache.roller.business;
020:
021: import java.util.Date;
022: import java.util.List;
023: import java.util.Map;
024: import org.apache.roller.RollerException;
025: import org.apache.roller.pojos.Assoc;
026: import org.apache.roller.pojos.CommentData;
027: import org.apache.roller.pojos.HitCountData;
028: import org.apache.roller.pojos.UserData;
029: import org.apache.roller.pojos.WeblogCategoryData;
030: import org.apache.roller.pojos.WeblogEntryData;
031: import org.apache.roller.pojos.WebsiteData;
032:
033: /**
034: * Interface to weblog entry, category and comment management.
035: */
036: public interface WeblogManager {
037:
038: public static final String CATEGORY_ATT = "category.att";
039:
040: /**
041: * Save weblog entry.
042: */
043: public void saveWeblogEntry(WeblogEntryData entry)
044: throws RollerException;
045:
046: /**
047: * Remove weblog entry.
048: */
049: public void removeWeblogEntry(WeblogEntryData entry)
050: throws RollerException;
051:
052: /**
053: * Get weblog entry by id.
054: */
055: public WeblogEntryData getWeblogEntry(String id)
056: throws RollerException;
057:
058: /**
059: * Get weblog entry by anchor.
060: */
061: public WeblogEntryData getWeblogEntryByAnchor(WebsiteData website,
062: String anchor) throws RollerException;
063:
064: /**
065: * Get WeblogEntries by offset/length as list in reverse chronological order.
066: * The range offset and list arguments enable paging through query results.
067: * @param website Weblog or null to get for all weblogs.
068: * @param user User or null to get for all users.
069: * @param startDate Start date or null for no start date.
070: * @param endDate End date or null for no end date.
071: * @param catName Category path or null for all categories.
072: * @param status Status of DRAFT, PENDING, PUBLISHED or null for all
073: * @param sortBy Sort by either 'pubTime' or 'updateTime' (null for pubTime)
074: * @param offset Offset into results for paging
075: * @param length Max comments to return (or -1 for no limit)
076: * @return List of WeblogEntryData objects in reverse chrono order.
077: * @throws RollerException
078: */
079: public List getWeblogEntries(WebsiteData website, UserData user,
080: Date startDate, Date endDate, String catName, List tags,
081: String status, String sortBy, String locale, int offset,
082: int range) throws RollerException;
083:
084: /**
085: * Get Weblog Entries grouped by day. This method returns a Map that
086: * contains Lists, each List contains WeblogEntryData objects, and the
087: * Lists are keyed by Date objects.
088: * @param website Weblog or null to get for all weblogs.
089: * @param startDate Start date or null for no start date.
090: * @param endDate End date or null for no end date.
091: * @param catName Category path or null for all categories.
092: * @param status Status of DRAFT, PENDING, PUBLISHED or null for all
093: * @param offset Offset into results for paging
094: * @param length Max comments to return (or -1 for no limit)
095: * @return Map of Lists, keyed by Date, and containing WeblogEntryData.
096: * @throws RollerException
097: */
098: public Map getWeblogEntryObjectMap(WebsiteData website,
099: Date startDate, Date endDate, String catName, List tags,
100: String status, String locale, int offset, int range)
101: throws RollerException;
102:
103: /**
104: * Get Weblog Entry date strings grouped by day. This method returns a Map
105: * that contains Lists, each List contains YYYYMMDD date strings objects,
106: * and the Lists are keyed by Date objects.
107: * @param website Weblog or null to get for all weblogs.
108: * @param startDate Start date or null for no start date.
109: * @param endDate End date or null for no end date.
110: * @param catName Category path or null for all categories.
111: * @param status Status of DRAFT, PENDING, PUBLISHED or null for all
112: * @param offset Offset into results for paging
113: * @param length Max comments to return (or -1 for no limit)
114: * @return Map of Lists, keyed by Date, and containing date strings.
115: * @throws RollerException
116: */
117: public Map getWeblogEntryStringMap(WebsiteData website,
118: Date startDate, Date endDate, String catName, List tags,
119: String status, String locale, int offset, int range)
120: throws RollerException;
121:
122: /**
123: * Get weblog entries with given category or, optionally, any sub-category
124: * of that category.
125: * @param cat Category
126: * @param subcats True if sub-categories are to be fetched
127: * @return List of weblog entries in category
128: */
129: public List getWeblogEntries(WeblogCategoryData cat, boolean subcats)
130: throws RollerException;
131:
132: /**
133: * Get weblog enties ordered by descending number of comments.
134: * @param website Weblog or null to get for all weblogs.
135: * @param startDate Start date or null for no start date.
136: * @param endDate End date or null for no end date.
137: * @param offset Offset into results for paging
138: * @param length Max comments to return (or -1 for no limit)
139: * @returns List of WeblogEntryData objects.
140: */
141: public List getMostCommentedWeblogEntries(WebsiteData website,
142: Date startDate, Date endDate, int offset, int length)
143: throws RollerException;
144:
145: /**
146: * Get the WeblogEntry following, chronologically, the current entry.
147: * Restrict by the Category, if named.
148: * @param current The "current" WeblogEntryData
149: * @param catName The value of the requested Category Name
150: */
151: public WeblogEntryData getNextEntry(WeblogEntryData current,
152: String catName, String locale) throws RollerException;
153:
154: /**
155: * Get the WeblogEntry prior to, chronologically, the current entry.
156: * Restrict by the Category, if named.
157: * @param current The "current" WeblogEntryData.
158: * @param catName The value of the requested Category Name.
159: */
160: public WeblogEntryData getPreviousEntry(WeblogEntryData current,
161: String catName, String locale) throws RollerException;
162:
163: /**
164: * Get entries next after current entry.
165: * @param entry Current entry.
166: * @param catName Only return entries in this category (if not null).
167: * @param maxEntries Maximum number of entries to return.
168: */
169: public List getNextEntries(WeblogEntryData entry, String catName,
170: String locale, int maxEntries) throws RollerException;
171:
172: /**
173: * Get entries previous to current entry.
174: * @param entry Current entry.
175: * @param catName Only return entries in this category (if not null).
176: * @param maxEntries Maximum number of entries to return.
177: */
178: public List getPreviousEntries(WeblogEntryData entry,
179: String catName, String locale, int maxEntries)
180: throws RollerException;
181:
182: /**
183: * Get specified number of most recent pinned and published Weblog Entries.
184: * @param max Maximum number to return.
185: * @return Collection of WeblogEntryData objects.
186: */
187: public List getWeblogEntriesPinnedToMain(Integer max)
188: throws RollerException;
189:
190: /** Get time of last update for a weblog specified by username */
191: public Date getWeblogLastPublishTime(WebsiteData website)
192: throws RollerException;
193:
194: /**
195: * Gets returns most recent pubTime, optionally restricted by category.
196: * @param handle Handle of website or null for all users
197: * @param catName Category name of posts or null for all categories
198: * @return Date Of last publish time
199: */
200: public Date getWeblogLastPublishTime(WebsiteData website,
201: String catName) throws RollerException;
202:
203: /**
204: * Save weblog category.
205: */
206: public void saveWeblogCategory(WeblogCategoryData cat)
207: throws RollerException;
208:
209: /**
210: * Remove weblog category.
211: */
212: public void removeWeblogCategory(WeblogCategoryData cat)
213: throws RollerException;
214:
215: /**
216: * Get category by id.
217: */
218: public WeblogCategoryData getWeblogCategory(String id)
219: throws RollerException;
220:
221: /**
222: * Recategorize all entries with one category to another.
223: */
224: public void moveWeblogCategoryContents(WeblogCategoryData srcCat,
225: WeblogCategoryData destCat) throws RollerException;
226:
227: /**
228: * Get top level categories for a website.
229: * @param website Website.
230: */
231: public WeblogCategoryData getRootWeblogCategory(WebsiteData website)
232: throws RollerException;
233:
234: /**
235: * Get category specified by website and categoryPath.
236: * @param website Website of WeblogCategory.
237: * @param categoryPath Path of WeblogCategory, relative to category root.
238: */
239: public WeblogCategoryData getWeblogCategoryByPath(
240: WebsiteData website, String categoryPath)
241: throws RollerException;
242:
243: /**
244: * Get sub-category by path relative to specified category.
245: * @param category Root of path or null to start at top of category tree.
246: * @param path Path of category to be located.
247: * @param website Website of categories.
248: * @return Category specified by path or null if not found.
249: */
250: public WeblogCategoryData getWeblogCategoryByPath(WebsiteData wd,
251: WeblogCategoryData category, String string)
252: throws RollerException;
253:
254: /**
255: * Get WebLogCategory objects for a website.
256: */
257: public List getWeblogCategories(WebsiteData website)
258: throws RollerException;
259:
260: /**
261: * Get WebLogCategory objects for a website.
262: */
263: public List getWeblogCategories(WebsiteData website,
264: boolean includeRoot) throws RollerException;
265:
266: /**
267: * Get absolute path to category, appropriate for use by getWeblogCategoryByPath().
268: * @param category WeblogCategoryData.
269: * @return Forward slash separated path string.
270: */
271: public String getPath(WeblogCategoryData category)
272: throws RollerException;
273:
274: /**
275: * Get parent association for a category.
276: */
277: public Assoc getWeblogCategoryParentAssoc(WeblogCategoryData data)
278: throws RollerException;
279:
280: /**
281: * Get child associations for a category.
282: */
283: public List getWeblogCategoryChildAssocs(WeblogCategoryData data)
284: throws RollerException;
285:
286: /**
287: * Get all descendent associations for a category.
288: */
289: public List getAllWeblogCategoryDecscendentAssocs(
290: WeblogCategoryData data) throws RollerException;
291:
292: /**
293: * Get all ancestor associates for a category.
294: */
295: public List getWeblogCategoryAncestorAssocs(WeblogCategoryData data)
296: throws RollerException;
297:
298: /**
299: * Save comment.
300: */
301: public void saveComment(CommentData comment) throws RollerException;
302:
303: /**
304: * Remove comment.
305: */
306: public void removeComment(CommentData comment)
307: throws RollerException;
308:
309: /**
310: * Get comment by id.
311: */
312: public CommentData getComment(String id) throws RollerException;
313:
314: /**
315: * Generic comments query method.
316: * @param website Website or null for all comments on site
317: * @param entry Entry or null to include all comments
318: * @param startDate Start date or null for no restriction
319: * @param endDate End date or null for no restriction
320: * @param pending Pending flag value or null for no restriction
321: * @param approved Approved flag value or null for no restriction
322: * @param reverseChrono True for results in reverse chrono order
323: * @param spam Spam flag value or null for no restriction
324: * @param offset Offset into results for paging
325: * @param length Max comments to return (or -1 for no limit)
326: */
327: public List getComments(WebsiteData website, WeblogEntryData entry,
328: String searchString, Date startDate, Date endDate,
329: Boolean pending, Boolean approved, Boolean spam,
330: boolean reverseChrono, int offset, int length)
331: throws RollerException;
332:
333: /**
334: * Deletes comments that match paramters.
335: * @param website Website or null for all comments on site
336: * @param entry Entry or null to include all comments
337: * @param startDate Start date or null for no restriction
338: * @param endDate End date or null for no restriction
339: * @param approved Pending flag value or null for no restriction
340: * @param pending Approved flag value or null for no restriction
341: * @return Number of comments deleted
342: */
343: public int removeMatchingComments(WebsiteData website,
344: WeblogEntryData entry, String searchString, Date startDate,
345: Date endDate, Boolean pending, Boolean approved,
346: Boolean spam) throws RollerException;
347:
348: /**
349: * Create unique anchor for weblog entry.
350: */
351: public String createAnchor(WeblogEntryData data)
352: throws RollerException;
353:
354: /**
355: * Check for duplicate category name.
356: */
357: public boolean isDuplicateWeblogCategoryName(WeblogCategoryData data)
358: throws RollerException;
359:
360: /**
361: * Check if weblog category is in use.
362: */
363: public boolean isWeblogCategoryInUse(WeblogCategoryData data)
364: throws RollerException;
365:
366: /**
367: * Returns true if ancestor is truly an ancestor of child.
368: */
369: public boolean isDescendentOf(WeblogCategoryData child,
370: WeblogCategoryData ancestor) throws RollerException;
371:
372: /**
373: * Apply comment default settings from website to all of website's entries.
374: */
375: public void applyCommentDefaultsToEntries(WebsiteData website)
376: throws RollerException;
377:
378: /**
379: * Release all resources held by manager.
380: */
381: public void release();
382:
383: /**
384: * Get list of TagStat. There's no offset/length params just a limit.
385: * @param website Weblog or null to get for all weblogs.
386: * @param startDate Date or null of the most recent time a tag was used.
387: * @param limit Max TagStats to return (or -1 for no limit)
388: * @return
389: * @throws RollerException
390: */
391: public List getPopularTags(WebsiteData website, Date startDate,
392: int limit) throws RollerException;
393:
394: /**
395: * Get list of TagStat. There's no offset/length params just a limit.
396: * @param website Weblog or null to get for all weblogs.
397: * @param sortBy Sort by either 'name' or 'count' (null for name)
398: * @param startsWith Prefix for tags to be returned (null or a string of length > 0)
399: * @param limit Max TagStats to return (or -1 for no limit)
400: * @return
401: * @throws RollerException
402: */
403: public List getTags(WebsiteData website, String sortBy,
404: String startsWith, int limit) throws RollerException;
405:
406: /**
407: * Does the specified tag combination exist? Optionally confined to a specific weblog.
408: *
409: * This tests if the intersection of the tags listed will yield any results
410: * and returns a true/false value if so. This means that if the tags list
411: * is "foo", "bar" and only the tag "foo" has been used then this method
412: * should return false.
413: *
414: * @param tags The List of tags to check for.
415: * @param weblog The weblog to confine the check to.
416: * @return True if tags exist, false otherwise.
417: * @throws RollerException If there is any problem doing the operation.
418: */
419: public boolean getTagComboExists(List tags, WebsiteData weblog)
420: throws RollerException;
421:
422: /**
423: * This method maintains the tag aggregate table up-to-date with total counts. More
424: * specifically every time this method is called it will act upon exactly two rows
425: * in the database (tag,website,count), one with website matching the argument passed
426: * and one where website is null. If the count ever reaches zero, the row must be deleted.
427: *
428: * @param name The tag name
429: * @param website The website to used when updating the stats.
430: * @param amount The amount to increment the tag count (it can be positive or negative).
431: * @throws RollerException
432: */
433: public void updateTagCount(String name, WebsiteData website,
434: int amount) throws RollerException;
435:
436: /**
437: * Get a HitCountData by id.
438: *
439: * @param id The HitCountData id.
440: * @return The HitCountData object, or null if it wasn't found.
441: * @throws RollerException If there was a problem with the backend.
442: */
443: public HitCountData getHitCount(String id) throws RollerException;
444:
445: /**
446: * Get a HitCountData by weblog.
447: *
448: * @param weblog The WebsiteData that you want the hit count for.
449: * @return The HitCountData object, or null if it wasn't found.
450: * @throws RollerException If there was a problem with the backend.
451: */
452: public HitCountData getHitCountByWeblog(WebsiteData weblog)
453: throws RollerException;
454:
455: /**
456: * Get HitCountData objects for the hotest weblogs.
457: *
458: * The results may be constrained to a certain number of days back from the
459: * current time, as well as pagable via the offset and length params.
460: *
461: * The results are ordered by highest counts in descending order, and any
462: * weblogs which are not active or enabled are not included.
463: *
464: * @param sinceDays Number of days in the past to consider.
465: * @param offset What index in the results to begin from.
466: * @param length The number of results to return.
467: * @return The list of HitCountData objects ranked by hit count, descending.
468: * @throws RollerException If there was a problem with the backend.
469: */
470: public List getHotWeblogs(int sinceDays, int offset, int length)
471: throws RollerException;
472:
473: /**
474: * Save a HitCountData object.
475: *
476: * @param hitCount The HitCountData object to save.
477: * @throws RollerException If there was a problem with the backend.
478: */
479: public void saveHitCount(HitCountData hitCount)
480: throws RollerException;
481:
482: /**
483: * Remove a HitCountData object.
484: *
485: * @param hitCount The HitCountData object to remove.
486: * @throws RollerException If there was a problem with the backend.
487: */
488: public void removeHitCount(HitCountData hitCount)
489: throws RollerException;
490:
491: /**
492: * Increment the hit count for a weblog by a certain amount.
493: *
494: * This is basically a convenience method for doing a lookup, modify, save
495: * of a HitCountData object.
496: *
497: * @param weblog The WebsiteData object to increment the count for.
498: * @param amount How much to increment by.
499: * @throws RollerException If there was a problem with the backend.
500: */
501: public void incrementHitCount(WebsiteData weblog, int amount)
502: throws RollerException;
503:
504: /**
505: * Reset the hit counts for all weblogs. This sets the counts back to 0.
506: *
507: * @throws RollerException If there was a problem with the backend.
508: */
509: public void resetAllHitCounts() throws RollerException;
510:
511: /**
512: * Reset the hit counts for a single weblog. This sets the count to 0.
513: *
514: * @param weblog The WebsiteData object to reset the count for.
515: * @throws RollerException If there was a problem with the backend.
516: */
517: public void resetHitCount(WebsiteData weblog)
518: throws RollerException;
519:
520: }
|