Jive Forums API (5.5.20.2-oracle) Web Services Client Javadocs

com.jivesoftware.forum.webservices
Interface AnnouncementService


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 getForumAnnouncementCountWithFilter(long forumID, AnnouncementFilter filter)
          Returns the number of viewable announcements using the specified forumID and AnnouncementFilter.
 Announcement[] getForumAnnouncementsWithFilter(long forumID, AnnouncementFilter filter)
          Returns the viewable announcements using the specified forumID and AnnouncementFilter.
 int getRecursiveCategoryAnnouncementCount(long categoryID)
          Returns the number of viewable announcements recursively using the categoryID provided.
 int getRecursiveCategoryAnnouncementCountWithFilter(long categoryID, AnnouncementFilter filter)
          Returns the number of viewable announcements recursively using the specified categoryID and AnnouncementFilter.
 Announcement[] getRecursiveCategoryAnnouncements(long categoryID, int startIndex, int numResults)
          Returns the viewable announcements recursively using the categoryID provided.
 Announcement[] getRecursiveCategoryAnnouncementsWithFilter(long categoryID, AnnouncementFilter filter)
          Returns the viewable announcements recursively using the specified categoryID and AnnouncementFilter.
 int getSystemAnnouncementCountWithFilter(AnnouncementFilter filter)
          Returns the number of viewable system announcements using the specified AnnouncementFilter.
 Announcement[] getSystemAnnouncementsWithFilter(AnnouncementFilter filter)
          Returns the viewable system announcements using the specified AnnouncementFilter.
 

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

getSystemAnnouncementCountWithFilter

int getSystemAnnouncementCountWithFilter(AnnouncementFilter filter)
Returns the number of viewable system announcements using the specified AnnouncementFilter.

Parameters:
filter - the AnnouncementFilter
Returns:
the number of system Announcements.

getSystemAnnouncementsWithFilter

Announcement[] getSystemAnnouncementsWithFilter(AnnouncementFilter filter)
Returns the viewable system announcements using the specified AnnouncementFilter.

Parameters:
filter - the AnnouncementFilter
Returns:
the system Announcements.

getForumAnnouncementCountWithFilter

int getForumAnnouncementCountWithFilter(long forumID,
                                        AnnouncementFilter filter)
                                        throws ForumNotFoundException
Returns the number of viewable announcements using the specified forumID and AnnouncementFilter.

Parameters:
forumID - the forum ID
filter - the AnnouncementFilter
Returns:
the number of Announcements in the forum.
Throws:
ForumNotFoundException - if the forum is not found.

getForumAnnouncementsWithFilter

Announcement[] getForumAnnouncementsWithFilter(long forumID,
                                               AnnouncementFilter filter)
                                               throws ForumNotFoundException
Returns the viewable announcements using the specified forumID and AnnouncementFilter.

Parameters:
forumID - the forum ID
filter - the AnnouncementFilter
Returns:
the Announcements in the forum.
Throws:
ForumNotFoundException - if the forum is not found.

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.

getRecursiveCategoryAnnouncementCountWithFilter

int getRecursiveCategoryAnnouncementCountWithFilter(long categoryID,
                                                    AnnouncementFilter filter)
                                                    throws ForumCategoryNotFoundException
Returns the number of viewable announcements recursively using the specified categoryID and AnnouncementFilter. This can include System Announcements, Category Announcements, and Forum Announcements. To include System Announcements, use -1.

Parameters:
categoryID - the category ID, or -1 to start with System Announcements
filter - the AnnouncementFilter
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.

getRecursiveCategoryAnnouncementsWithFilter

Announcement[] getRecursiveCategoryAnnouncementsWithFilter(long categoryID,
                                                           AnnouncementFilter filter)
                                                           throws ForumCategoryNotFoundException
Returns the viewable announcements recursively using the specified categoryID and AnnouncementFilter. This can include System Announcements, Category Announcements, and Forum Announcements. To include System Announcements, use -1.

Parameters:
categoryID - the category ID, or -1 to start with System Announcements
filter - the AnnouncementFilter
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

Jive Forums Project Page

Copyright © 1999-2006 Jive Software.