com.jivesoftware.forum.webservices
Interface AnnouncementService

All Known Implementing Classes:

AnnouncementServiceImpl

public interface AnnouncementService

Provides the ability to manipulate announcements. This service will allow you to create, delete, and expire announcements.

Method Summary

Announcement	createForumAnnouncement(long userID, long forumID, java.lang.String subject, java.lang.String body, java.util.Date startDate, java.util.Date endDate) Creates a new category or forum announcement.
Announcement	createForumCategoryAnnouncement(long userID, long categoryID, java.lang.String subject, java.lang.String body, java.util.Date startDate, java.util.Date endDate) Creates a new category announcement.
Announcement	createNonExpiringForumAnnouncement(long userID, long forumID, java.lang.String subject, java.lang.String body, java.util.Date startDate) Creates a new non-expiring forum announcement.
Announcement	createNonExpiringForumCategoryAnnouncement(long userID, long categoryID, java.lang.String subject, java.lang.String body, java.util.Date startDate) Creates a new non-expiring category announcement.
Announcement	createNonExpiringSystemAnnouncement(long userID, java.lang.String subject, java.lang.String body, java.util.Date startDate) Creates a new non-expiring system announcement.
Announcement	createSystemAnnouncement(long userID, java.lang.String subject, java.lang.String body, java.util.Date startDate, java.util.Date endDate) Creates a new system announcement.
void	deleteAnnouncement(long announcementID) Deletes an announcement.
void	editAnnouncement(Announcement announcement) Updates an existing announcement.
void	expireAnnouncement(long announcementID) Expires an announcement.
Announcement	getAnnouncement(long announcementID) Returns an announcement by announcement ID.
int	getAnnouncementCount(int objectType, long objectID) Returns the count of all currently viewable announcements in a container.
int	getAnnouncementCount(int objectType, long objectID, java.util.Date startDate, java.util.Date endDate) Returns the count of all announcements in a container that are viewable within the specified date range.
Announcement[]	getAnnouncements(int objectType, long objectID) Returns all currently viewable announcements in a container.
Announcement[]	getAnnouncements(int objectType, long objectID, java.util.Date startDate, java.util.Date endDate) Returns the announcements in a container that are viewable within a specified date range.If container is null than system announcements will be returned.
int	getRecursiveCategoryAnnouncementCount(long categoryID) Returns the number of viewable announcements recursively using the categoryID provided.
Announcement[]	getRecursiveCategoryAnnouncements(long categoryID, int startIndex, int numResults) Returns the viewable announcements recursively using the categoryID provided.

Method Detail

createSystemAnnouncement

Announcement createSystemAnnouncement(long userID,
                                      java.lang.String subject,
                                      java.lang.String body,
                                      java.util.Date startDate,
                                      java.util.Date endDate)
                                      throws UserNotFoundException,
                                             UnauthorizedException

Creates a new system announcement.

Parameters:

userID - the ID of the user creating the announcement.

subject - the subject of the announcement.

body - the body of the announcement.

startDate - the start date for the announcement. Cannot be null.

endDate - the end date for the announcement. Cannot be null.

Returns:

a new Announcement.

Throws:

UnauthorizedException - if not allowed to create a system annoucement.

UserNotFoundException

createNonExpiringSystemAnnouncement

Announcement createNonExpiringSystemAnnouncement(long userID,
                                                 java.lang.String subject,
                                                 java.lang.String body,
                                                 java.util.Date startDate)
                                                 throws UserNotFoundException,
                                                        UnauthorizedException

Creates a new non-expiring system announcement.

Parameters:

userID - the ID of the user creating the announcement.

subject - the subject of the announcement.

body - the body of the announcement.

startDate - the start date for the announcement. Cannot be null.

Returns:

a new Announcement.

Throws:

UnauthorizedException - if not allowed to create a system annoucement.

UserNotFoundException

createForumAnnouncement

Announcement createForumAnnouncement(long userID,
                                     long forumID,
                                     java.lang.String subject,
                                     java.lang.String body,
                                     java.util.Date startDate,
                                     java.util.Date endDate)
                                     throws UserNotFoundException,
                                            ForumNotFoundException,
                                            UnauthorizedException

Creates a new category or forum announcement.

Parameters:

userID - the user ID creating the announcement.

forumID, - the ID of the Forum.

subject - the subject of the announcement.

body - the body of the announcement.

startDate - the start date for the announcement. Cannot be null.

endDate - the end date for the announcement. Cannot be null.

Returns:

a new Announcement.

Throws:

UnauthorizedException - if not allowed to create a system annoucement.

ForumCategoryNotFoundException - if the category is not found.

ForumNotFoundException - if the forum is not found.

UserNotFoundException

createNonExpiringForumAnnouncement

Announcement createNonExpiringForumAnnouncement(long userID,
                                                long forumID,
                                                java.lang.String subject,
                                                java.lang.String body,
                                                java.util.Date startDate)
                                                throws UserNotFoundException,
                                                       ForumNotFoundException,
                                                       UnauthorizedException

Creates a new non-expiring forum announcement.

Parameters:

userID - the user ID creating the announcement.

forumID, - the ID of the Forum.

subject - the subject of the announcement.

body - the body of the announcement.

startDate - the start date for the announcement. Cannot be null.

Returns:

a new Announcement.

Throws:

UnauthorizedException - if not allowed to create a system annoucement.

ForumCategoryNotFoundException - if the category is not found.

ForumNotFoundException - if the forum is not found.

UserNotFoundException

createForumCategoryAnnouncement

Announcement createForumCategoryAnnouncement(long userID,
                                             long categoryID,
                                             java.lang.String subject,
                                             java.lang.String body,
                                             java.util.Date startDate,
                                             java.util.Date endDate)
                                             throws UserNotFoundException,
                                                    ForumCategoryNotFoundException,
                                                    UnauthorizedException

Creates a new category announcement.

Parameters:

userID - the user ID creating the announcement.

categoryID, - the ID of the Forum.

subject - the subject of the announcement.

body - the body of the announcement.

startDate - the start date for the announcement. Cannot be null.

endDate - the end date for the announcement. Cannot be null.

Returns:

a new Announcement.

Throws:

UnauthorizedException - if not allowed to create a system annoucement.

ForumCategoryNotFoundException - if the category is not found.

ForumNotFoundException - if the forum is not found.

UserNotFoundException

createNonExpiringForumCategoryAnnouncement

Announcement createNonExpiringForumCategoryAnnouncement(long userID,
                                                        long categoryID,
                                                        java.lang.String subject,
                                                        java.lang.String body,
                                                        java.util.Date startDate)
                                                        throws UserNotFoundException,
                                                               ForumCategoryNotFoundException,
                                                               UnauthorizedException

Creates a new non-expiring category announcement.

Parameters:

userID - the user ID creating the announcement.

categoryID, - the ID of the Forum.

subject - the subject of the announcement.

body - the body of the announcement.

startDate - the start date for the announcement. Cannot be null.

Returns:

a new Announcement.

Throws:

UnauthorizedException - if not allowed to create a system annoucement.

ForumCategoryNotFoundException - if the category is not found.

ForumNotFoundException - if the forum is not found.

UserNotFoundException

getAnnouncement

Announcement getAnnouncement(long announcementID)
                             throws AnnouncementNotFoundException,
                                    UnauthorizedException

Returns an announcement by announcement ID.

Parameters:

announcementID - the ID of the announcement to return.

Returns:

the announcement.

Throws:

AnnouncementNotFoundException - if the announcement could not be loaded or does not exist.

UnauthorizedException - if not allowed to get the announcement.

editAnnouncement

void editAnnouncement(Announcement announcement)
                      throws AnnouncementNotFoundException

Updates an existing announcement. Use an Announcement object retrieved from a prior webservice call as an argument, in order to maintain database consistancy for all attributes in the Announcement object. Fields that can be changed include subject, body, startDate, and endDate. The Announcement is not returned since no attributes will change within the service call.

Parameters:

announcement - the announcement to update.

Throws:

AnnouncementNotFoundException

getAnnouncementCount

int getAnnouncementCount(int objectType,
                         long objectID)
                         throws ForumNotFoundException,
                                ForumCategoryNotFoundException

Returns the count of all currently viewable announcements in a container. If container is null than the count of system announcements will be returned. Otherwise, the container should be a ForumCategory or Forum object.

Parameters:

objectType - a forum, category, or -1 for system announcements.

objectID - an ID of a forums, category, or -1 for system announcmenents.

Returns:

the count of all currently viewable announcements in the container.

Throws:

ForumNotFoundException

ForumCategoryNotFoundException

getAnnouncementCount

int getAnnouncementCount(int objectType,
                         long objectID,
                         java.util.Date startDate,
                         java.util.Date endDate)
                         throws ForumNotFoundException,
                                ForumCategoryNotFoundException

Returns the count of all announcements in a container that are viewable within the specified date range. If objectType and objectID is -1 then the count of system announcements will be returned. Otherwise, the objectType and objectID should reference a ForumCategory or Forum object. If startDate or endDate are null than the date range will be unbounded in that direction. For example, to get a count of all announcements regardless of starting and ending dates, pass in null as the value for both parameters.

Parameters:

objectType - a forum, category, or -1 for system announcements.

objectID - an ID of a forums, category, or -1 for system announcmenents.

startDate - the start date of announcements, or null to leave this value unbounded.

endDate - the end date of announcements, or null to leave this value unbounded.

Returns:

the count of all announcements in the container that are viewable within the specified date range.

Throws:

ForumNotFoundException

ForumCategoryNotFoundException

getAnnouncements

Announcement[] getAnnouncements(int objectType,
                                long objectID)
                                throws ForumNotFoundException,
                                       ForumCategoryNotFoundException

Returns all currently viewable announcements in a container. If objectType and objectID is -1 than system announcements will be returned. Otherwise, the container should be a ForumCategory or Forum object.

Parameters:

objectType - a forum, category, or -1 for system announcements.

objectID - an ID of a forums, category, or -1 for system announcmenents.

Returns:

the currently viewable announcements in the container.

Throws:

ForumNotFoundException

ForumCategoryNotFoundException

getAnnouncements

Announcement[] getAnnouncements(int objectType,
                                long objectID,
                                java.util.Date startDate,
                                java.util.Date endDate)
                                throws ForumNotFoundException,
                                       ForumCategoryNotFoundException

Returns the announcements in a container that are viewable within a specified date range.If container is null than system announcements will be returned. Otherwise, the container should be a ForumCategory or Forum object. If startDate or endDate are null than the date range will be unbounded in that direction. For example, to get all announcements regardless of starting and ending dates, pass in null as the value for both parameters.

Parameters:

objectType - a forum, category, or -1 for system announcements.

objectID - an ID of a forums, category, or -1 for system announcmenents.

startDate - the start date of announcements, or null to leave this value unbounded.

endDate - the end date of announcements, or null to leave this value unbounded.

Returns:

all announcements in the container that are viewable within the the specified date range.

Throws:

ForumNotFoundException

ForumCategoryNotFoundException

getRecursiveCategoryAnnouncementCount

int getRecursiveCategoryAnnouncementCount(long categoryID)
                                          throws ForumCategoryNotFoundException

Returns the number of viewable announcements recursively using the categoryID provided. This can include System Announcments, Category Announcement, and Forum Announcements. To include System Announcements, use -1.

Parameters:

categoryID - the category ID, or -1 to start with System Announcements

Returns:

the number of Announcements at or below the category ID in the hierarchy.

Throws:

ForumCategoryNotFoundException - if the category is not found.

getRecursiveCategoryAnnouncements

Announcement[] getRecursiveCategoryAnnouncements(long categoryID,
                                                 int startIndex,
                                                 int numResults)
                                                 throws ForumCategoryNotFoundException

Returns the viewable announcements recursively using the categoryID provided. This can include System Announcments, Category Announcement, and Forum Announcements. To include System Announcements, use -1. To control the number of results returned, user the startIndex (0 or greater) and numResults (0 to Integer.MAX_VALUE).

Parameters:

categoryID - the category ID, or -1 to start with System Announcements

startIndex - the 0 based index to start at.

numResults - the number of results to returned, or Integer.MAX_VALUE for all results.

Returns:

the Announcements at or below the category ID in the hierarchy.

Throws:

ForumCategoryNotFoundException - if the category is not found.

deleteAnnouncement

void deleteAnnouncement(long announcementID)
                        throws UnauthorizedException,
                               AnnouncementNotFoundException

Deletes an announcement.

Parameters:

announcementID - the ID of the announcement to delete.

Throws:

UnauthorizedException - if not allowed to delete the announcement.

AnnouncementNotFoundException

expireAnnouncement

void expireAnnouncement(long announcementID)
                        throws UnauthorizedException,
                               AnnouncementNotFoundException

Expires an announcement.

Parameters:

announcementID - the ID of the announcement to delete.

Throws:

UnauthorizedException - if not allowed to delete the announcement.

AnnouncementNotFoundException