Lead: Andrew Wright

This document describes various technical aspects of the Jive Forums Web Services implementation. Each service and object is described and several examples of the client APIs are available.

Contents

Overview

Jive Forums Web Services implement the SOAP protocol. WSDL description files are available as part of the distribution or by requesting the following URL from your Jive Forums instance: http://myhost.com/forums/rpc/soap/.

Web Service Style

Jive Forums Web Services use Document-Literal style binding with wrapped parameter format. This style was chosen for a number of reasons: it is WS-I compliant, the message is easily validateable. There is also a general push towards Document-Literal style web services.

For a general description about web services styles see: http://www.ibm.com/developerworks/webservices/library/ws-whichwsdl/

Authentication

Jive Forums Web Services uses the Username Token Profile V1.0 (pdf) specification. The Username Token Profile specification is part of the OASIS Web Services Security (WS-Security) specification.

A header containing the username and password must be passed into every request.

<wsdl:Envelope xmlns:soap="..."
        xmlns:wsse="..." >
       <wsdl:Header>
       <wsse:Security>
       <wsse:UsernameToken>
       <wsse:Username>admin</wsse:Username>
       <wsse:Password>password</wsse:Password>
       </wsse:UsernameToken>
       </wsse:Security>
       </wsdl:Header>
       </wsdl:Envelope>

Objects

Object Description
Forum A container for a list of threads.
ForumCategory A container for forums and a hierarchy of other forum categories.
ForumMessage A ForumMessage encapsulates message data.
ForumThread A ForumThread is a container for a hierarchy of ForumMessages.
Group Organizes users into a group for easier permissions management.
PrivateMessage  
PrivateMessageFolder  
User Provides information about and services for users of the system.
Watch A watch is a way for a user to track updates to an object.

Forum

Field Type Description
getID long Returns the unique id of the forum.
getName String Returns the name of the forum.
getNNTPName String Returns the NNTP name for the forum, which is the name of the forum used
in the NNTP protocol (newsgroups).
getDescription String Returns the description of the forum.
getCreationDate Date Returns the Date that the forum was created.
getModificationDate Date Returns the Date that the forum was last modified.
getModerationDefaultThreadValue int Returns the default number of moderation points for threads created in
the forum.
getModerationDefaultMessageValue int Returns the default number of moderation points for messages created in
the forum.
getMinForumIndex int Returns the smallest forum index value for a message in the forum.
getMaxForumIndex int Returns the largest forum index value for a message in the forum.
getLocale Locale Returns the locale for this forum.
getFinalLocale Locale Returns the locale for this forum.
getLatestMessageID long Returns the ID of the most recently created or edited message in this forum.
getCategoryID long Returns the parent category ID for this forum.

ForumCategory

Field Type Description
getID long Returns the ID of the category.
getName String Returns the name of the category.
getDescription String Returns the description of the forum category.
getCreationDate Date Returns the Date that the category was created.
getModificationDate Date Returns the Date this category was last modified.
getLocale Locale Returns the locale for this category.
getFinalLocale Locale Returns the locale for this category.
getForumCount int Returns the number of forums in the category.
getRecursiveForumCount int Returns the number of forums in the category and all sub-categories.
getThreadCount int Returns number of forums in the category and all sub-categories.
getMessageCount int Returns the number of messages in the category.
getLatestMessageID long Returns the most recently created or edited message in this category (including
all sub-categories).
getParentCategoryID long Returns ID of the parent category of this category.
getCategoryDepth int Returns the depth of a this category relative to the root.

ForumMessage

Field Type Description
getID long Returns the id of this message.
getForumIndex int Returns the index of this message in the forum.
getCreationDate Date Returns the date this message was created.
getModificationDate Date Returns the date this message was last modified.
getSubject String Returns the message subject.
getUnfilteredSubject String Returns the message subject, bypassing any active filters.
getBody String Returns the message body.
getUnfilteredBody String Returns the message body, bypassing any active filters.
getUserID long Returns the ID User that authored this message.
getParentMessageID long Returns the ID of the parent message of this message or <tt>0</tt> if this message is
the root message of a thread.
getAttachmentCount int Returns the number of attachments this message has.
getModerationValue int Returns the number of moderation points this message has.
getForumThreadID long Returns the ID of the thread this message belongs to.
getForumID long Returns the ID of the forum this message belongs to.

ForumThread

Field Type Description
getID long Returns the unique ID of this thread.
getName String Returns the subject of the root message of this thread.
getCreationDate Date Returns the date that this thread was created.
getModificationDate Date Returns the date that this thread was last modified.
getModerationValue int Returns the number of moderation points this thread has.
getForumID long Returns the ID of the forum this thread belongs to.
getRootMessageID long Returns the ID of the root message this thread.
getLatestMessageID long Returns the ID of the most recently created messages in this thread.
getMessageCount int Returns the number of messages in the thread.

Group

Field Type Description
getID long Returns the id of the group.
getName String Returns the name of the group.
getDescription String Returns the description of the group.
getCreationDate Date Returns the date that the group was created.
getModificationDate Date Returns the date that the group was last modified.
getMemberCount int Returns the number of users that belon gto this group.

PrivateMessage

Field Type Description
getId long  
getDate Date  
getSubject String  
getBody String  
getOwnerID long  
getSenderID long  
getRecipientID long  
getFolderID int  

PrivateMessageFolder

Field Type Description
getID int  
getOwnerID long  
getName String  
getMessageCount int  

User

Field Type Description
getID long Returns the user's id.
getUsername String Returns the user's username.
getName String Returns the user's name.
getPassword String  
getPasswordHash String Returns the user's password in hashed form.
getEmail String Returns the user's email address.
getCreationDate Date Returns the date that the user was created.
getModificationDate Date Returns the date that the user was last modified.

Watch

Field Type Description
getUserID long Returns the if of the user who is associated with this watch.
getObjectID long Returns the object ID of the object being watched.
getObjectType int Returns the object type of the object being watched.
getWatchType int Returns the type of the watch.

Services

Service Description
AttachmentManagerService A web service to manage attachment settings.
ContentService Provides a way to get handles on content objects.
ForumCategoryService Provides the ability to manipulate forum categories.
ForumMessageService Provides the ability to manipulate forum messages.
ForumService Provides the ability to manipulate forums.
ForumThreadService Provides the ability to manipulate forum threads.
GroupService Provides a the ability for managing groups and group membership.
PermissionService Provides a webservice for managing permissions on users and groups.
PrivateMessageService Provides the ability to manipulate private messages.
ProfileService Provides a webservice for managing user's, avatar's, and status levels.
SystemPropertiesService Provides a web service for managing Jive System Properties.
WatchService A service for manipulating a user's watches on objects.

Operations

AttachmentManagerService

A web service to manage attachment settings.

Field Type Description
isDatabaseModeEnabled boolean Returns true if the binary attachment data is stored in the database.
setDatabaseModeEnabled void Enables or disables storage of binary attachment data in the database.
getAttachmentDirectorySize long Returns the size (in bytes) of the attachment directory on the file system.
getMaxFilesystemCacheSize long Returns the maximum amount of storage (in bytes) that will be used by the
file system cache when database attachment mode is enabled.
setMaxFilesystemCacheSize void Sets the maximum amount of storage (in bytes) that will be used by the
file system cache when database attachment mode is enabled.
getMaxAttachmentSize int Returns the maximum size of an individual attachment in kilobytes.
setMaxAttachmentSize void Sets the maximum size of an individual attachment in kilobytes.
getMaxAttachmentsPerMessage int Returns the maximum number of attachments per message.
setMaxAttachmentsPerMessage void Sets the maximum number of attachments per message.
isValidType boolean Returns true if the content type is valid based on the current settings
of the <tt>allowAllByDefault</tt> flag and the allowed and disallowed
types list.
addAllowedType void Adds a content type to the list of explicitly allowed types.
removeAllowedType void Removes a content type fromt he list of explicitly allowed types.
allowedTypes String Returns a String[] for the list of explicitly allowed types.
addDisallowedType void Adds a content type to the list of explicitly disallowed types.
removeDisallowedType void Removes a content type from the list of explicitly disallowed types.
disallowedTypes String Returns an Iterator for the list of explicitly disallowed types.
getAllowAllByDefault boolean Returns true if in the "allow all content types by default" mode.
setAllowAllByDefault void Sets the default allowed content types mode.
isImagePreviewEnabled boolean Returns true if image preview support is enabled.
setImagePreviewEnabled void Toggles whether image preview support is enabled.
getImagePreviewMaxSize int Returns the max dimension of generated thumbnails (ie, the max value for
the width or height).
setImagePreviewMaxSize void Sets the max dimension of generated thumbnails (ie, the max value for
the width or height).
isImagePreviewRatioEnabled boolean Returns true if the aspect ratio of thumbnails should be preserved.
setImagePreviewRatioEnabled void Toggles whether the aspect ratio of thumbnails should be preserved.

ContentService

Provides a way to get handles on content objects.

Field Type Description
getForum Forum Returns a Forum by its id.
getForumCategory ForumCategory Returns a ForumCategory by its id.
getForumThread ForumThread Returns a ForumThread by its id.
getForumMessage ForumMessage Returns a ForumMessage by its id.
createThread ForumThread Creates a new thread.
createMessage ForumMessage Creates a new message on the given thread.
createReplyMessage ForumMessage Creates a new message that is a direct response to a given message.
messageSearch long Provides the ability to create complex search queries with the ability to change sorting, filtering, etc.
quickMessageSearch long Provides the ability to do quick search queries based on the provided string.
countMessageSearchResults int Returns the number of possible results for the specified query.
countQuickMessageSearchResults int Returns the number of possible results for the specified query.
messageSearchByCategories long Provides the ability to create complex search queries with the ability to change sorting, filtering, etc.
countMessageSearchResultsByCategoryID int Returns the number of possible results for the specified query by category.
quickMessageSearchByCategoryID long Provides the ability to do quick search queries based on the provided string.
countQuickMessageSearchResultsByCategoryID int Returns the number of possible results for the specified query.

ForumCategoryService

Provides the ability to manipulate forum categories.

Field Type Description
getForumCategory ForumCategory  
createCategory ForumCategory Creates a new ForumCategory as a sub-category of the root category using
the name and description.
createSubCategory ForumCategory Creates a new ForumCategory as a sub-category off of the specified category.
deleteCategory void  
updateCategory void  
getProperties Property Returns all tbe extended properties for the category with the specified id.
setProperty void Set an extended propery for the category with the given category id.
getProperty String Returns the extended property value for the specified name.
deleteProperty void Delete a property with the given name from the category with the given id.
getRecursiveCategories ForumCategory Returns all of the categories in the system recursively.
getRecursiveCategoriesByCategoryID ForumCategory Returns all of the categories under the specified category recursively.
getRecursiveCategoryCount int Returns a count of all the categories in the system.
getRecursiveCategoryCountByCategoryID int  

ForumMessageService

Provides the ability to manipulate forum messages.

Field Type Description
getForumMessage ForumMessage Returns a ForumMessage by its ID.
deleteMessage void Delete the message with the following id.
deleteMessageAndChildren void Delete the message with the specified id.
getProperties Property Returns all tbe extended properties for the message with the specified ID.
setProperty void Set an extended for the property with the given message id.
getProperty String Returns the value of the extended property for the message with the specified ID.
deleteProperty void Delete a property with the given name from the message with the given ID.
getUnfilteredProperties Property Returns the properties without applying filters to them first.
getAttachmentsByMessageID DataSource Returns an array of attachments that are attached to the specified message.
addAttachmentToMessage void Adds an attachment to the message with the specified ID.
getMessageIDsByForumIDAndFilter long  
getMessageIDsByForumID long Returns all of the message IDs for all of the message that are in the forum.
getMessageIDsByCategoryIDAndFilter long Returns all of the message IDs for all of the message that are in the category with the specified ID, filtered
by the the specified result filter.
getMessageIDsByCategoryID long Returns all of the message IDs for all of the message that are in the category.
getMessageCountsByForumIDAndFilter int Returns the number of messages that are in the forum with the specified id after the specified filter has been
applied.
getMessageCountsByForumID int Returns the number of messages that are in the forum.
getMessageCountByCategoryIDAndFilter int Returns the number of messages that are in the category with the specified id after the specified filter has been
applied.
getMessageCountByCategoryID int Returns the number of messages that are in the category.
getMessageIDsByThreadIDAndFilter long Returns all of the message IDs for all of the message that are in the thread after the specified filter has
been applied.
getMessageIDsByThreadID long Returns the IDs of the messages that are in the thread.
getMessageCountByThreadIDAndFilter int Returns the number of messages that are in the thread with the specified id after the specified filter has been
applied.
getMessageCountByThreadID int Returns the number of messages that are in the thread.
getMessagesByForumIDAndFilter ForumMessage  
getMessagesByForumID ForumMessage Returns all of the messages in the forum.
getMessagesByCategoryIDAndFilter ForumMessage Returns all of the messages that are in the category with the specified ID, filtered
by the the specified result filter.
getMessagesByCategoryID ForumMessage Returns all of the messages that are in the category.
getMessagesByThreadIDAndFilter ForumMessage Returns all of the messages that are in the thread after the specified filter has
been applied.
getMessagesByThreadID ForumMessage Returns the messages that are in the thread.
getRootMessage ForumMessage Returns the root of a thread.
hasParent boolean Returns true if the <code>child</code> message has a parent message.
getParent ForumMessage Returns the parent of the <code>child</code> ForumMessage.
getChild ForumMessage Returns the child of parent at index index in the parent's child array.
getChildren ForumMessage Returns an array of all the child messages of the parent.
getRecursiveChildren ForumMessage Returns an array for all child messages (and sub-children, etc) of
the parent.
isLeaf boolean Returns true if node is a leaf.
getRecursiveChildCount int Returns the total number of recursive children of a parent.
getIndexOfChild int Returns the index of child in parent.
getMessageDepth int Returns the depth of a message in the message tree hierarchy.
getChildCount int Returns the number of children of parent.
getRecursiveMessages ForumMessage Returns an array for all messages in the thread in depth-first order.
updateForumMessage void  

ForumService

Provides the ability to manipulate forums.

Field Type Description
getForum Forum Returns a Forum by its ID.
getForums Forum Returns the IDs of all forums under the root category.
getPopularForums Forum Returns the IDs of all popular forums.
getForumCount int Returns the count of all forums in the system.
deleteForum void Used to delete a forum by its ID.
mergeForums void Merges the content of two forums by copying the threads from
Forum with ID <tt>forumID2</tt> to forum with ID <tt>forumID1</tt>.
moveForums void Move the forum with the specified ID to the category with the specified ID.
getRecursiveForums Forum Returns an array of forum ids for all forums under the category with the specified ID recursively.
getForumsByCategoryID Forum Returns an array of IDs for all forums under this category.
getRecursiveForumCount int Returns the count of all forums under the category with the specified ID.
getProperties Property Returns all tbe extended properties for the forum with the forum with specified ID.
deleteProperty void Delete a property with the given name from the forum with the given forum ID.
setProperty void Set an extended for the property with the given forum ID.
getProperty String Returns the value for a given property name.
getForumCount int Returns the number of forums under the specified category.
createForum Forum Creates a new forum under the root category.
createForumUnderCategory Forum Creates a new forum under the specified category.
updateForum void Updates changes to a forum to the system.

ForumThreadService

Provides the ability to manipulate forum threads.

Field Type Description
getForumThread ForumThread Returns a ForumThread by its ID.
getPopularThreads ForumThread Returns an array of thread IDs for all the popular threads in the system.
getPopularThreadsByForumID ForumThread Returns an array of threadIDs for all the popular threads for a specific forum.
getThreadCountByForumID int Returns a count of all threads under the forum.
getThreadCountByForumIDAndFilter int Returns a count of all threads under the forum filtered by the specified result filter.
deleteThread void Deletes a thread with the specified ID.
moveThread void Moves the thread with the specified ID to the forum with the specified ID.
getProperties Property Returns all tbe extended properties for the thread with the specified ID.
setProperty void Set an extended for the property for the thread with the given ID.
getProperty String Returns the value of an extended property for the thread with the specified ID.
deleteProperty void Delete a property with the given name from the thread with the given ID.
getThreadsByForumID ForumThread Returns all of the IDs for threads a forum has.
getThreadsByForumIDAndFilter ForumThread Returns all of the IDs for threads a forum has filtered by the specified result filter.
getThreadsByCategoryID ForumThread Returns all of the IDs for threads a category.
getThreadsByCategoryIDAndFilter ForumThread Returns all of the IDs for threads a category has filtered by the specified result filter.
getThreadCountByCategoryID int Returns the number of threads in the specified category.
getThreadCountByCategoryIDAndFilter int Returns the number of threads in the specified category after being filtered by the specified filter.
getPopularThreadsByCategoryID ForumThread Returns an array of popular threads by category.

GroupService

Provides a the ability for managing groups and group membership.

Field Type Description
getGroup Group Returns a Group by its ID.
getGroupByName Group Returns a Group by its name.
getGroupMembers User Returns an array of all userIDs for all the members of a particular group.
getGroupCount int Returns a count of all groups in the system.
getGroups Group Returns an array of all the group IDs for all the groups in the system.
getUserGroups Group Returns an array of all the group IDs that a user belongs too.
getGroupAdmins User Returns an array of all the user IDs that administer this group.
getAdministratorCount int Returns the count of how many administrators there are for the group with the specified ID.
createGroup Group Creates a new group.
deleteGroup void Delete the group with the specified id.
updateGroup void Update the following group in the system.
getProperties Property Returns an array of all the extended properties for a group.
setProperty void Set a new extended property on the specified group.
deleteProperty void Deletes an extended property from the specfied group.
addMemberToGroup void Add the user with the specified userID to the group with the specified groupID.
addAdministratorToGroup void Make the user with the specified userID an administrator of the group with the specified groupID.
removeMemberFromGroup void Remove the user with the specified id from the group with the specified id.
removeAdministratorFromGroup void Remove the user with the specified ID as an administrator from the group with the specified ID.

PermissionService

Provides a webservice for managing permissions on users and groups.

Field Type Description
addPermissionToUser void Add the specified permission to the user with the specified id.
removePermissionFromUser void Remove the specified permission from the user with the specified id.
addPermissionToGroup void Add the specified permission to the group with the specified id.
removePermissionFromGroup void Remove the specified permission from the group with the specified id.
addForumPermissionToUser void Add the specified permission on the specified forum to the user with the specified id.
removeForumPermissionFromUser void Remove the specified permission on the specified forum from the user with the specified id.
addCategoryPermissionToUser void Add the specified permission on the specified category to the user with the specified id.
removeCategoryPermissionFromUser void Remove the specified permission on the specified category from the user with the specified id.
isAuthorized boolean Returns true if the current user has globally has the specified permission.
isAuthorizedOnForum boolean Returns true if the current user has the permission specified on the specified forum.
isAuthorizedOnCategory boolean Returns true if the current user has the permission specified on the specified category.
registeredUserHasPermission boolean Returns true if registered users have a particular permission globally.
registeredUserHasPermissionOnForum boolean Returns true if registered users have a particular permission on the forum with the specified ID.
registeredUserHasPermissionOnCategory boolean Returns true if registered users have a particular permission on the category with the specified ID.
anonymousUserHasPermission boolean Returns true if the anonymous users have a particular permission globally.
anonymousUserHasPermissionOnForum boolean Returns true if the anonymous users have a particular permission on the forum with the specified ID.
anonymousUserHasPermissionOnCategory boolean Returns true if the anonymous users have a particular permission on the category with the specified ID.
usersWithPermissionCount int Returns a count of the users that have a particular permission.
usersWithPermission long Returns all the userID's of users with a particular permission.
usersWithPermissionCountOnForum int Returns a count of the users that have a particular permission on the specified forum.
usersWithPermissionOnForum long Returns all the userID's of users with a particular permission on the specified forum.
usersWithPermissionCountOnCategory int Returns a count of the users that have a particular permission on the specified category.
usersWithPermissionOnCategory long Returns all the userID's of users with a particular permission on the specified category.
removeCategoryPermissionFromGroup void Remove the specified permission on the specified category from the group with the specified id.
addForumPermissionToGroup void Add the specified permission on the specified forum to the group with the specified id.
removeForumPermissionFromGroup void Remove the specified permission on the specified forum from the group with the specified id.
addCategoryPermissionToGroup void Add the specified permission on the specified category to the group with the specified id.
isUserAuthorized boolean Checks to see if a particular user has a praticular permission system wide.
isUserAuthorizedOnCategory boolean Checks to see if a particular user has a particular permission on the specified category.
isUserAuthorizedOnForum boolean Checks to see if a particular user has a particular permission on the specified forum.

PrivateMessageService

Provides the ability to manipulate private messages.

Field Type Description
isPrivateMessagesEnabled boolean Returns <tt>true</tt> if the feature is enabled, <tt>false</tt> otherwise.
getMessages PrivateMessage Returns all the messages in the folder sorted by date descending.
deleteMessage void Deletes a private message from the folder by moving it to the trash folder.
moveMessage void Moves a private message to another folder.
getMessageCount int Returns the total number of private messages a user has in their mailbox.
getMessageCountForFolder int Returns the message count on a specific folder.
getUnreadMessageCount int Returns the total number of unread private messages a user has in their mailbox.
getUnreadMessageCountForFolder int Returns the total number of unread private messages a user has in a specific folder.
getFolders PrivateMessageFolder Returns an Iterator of PrivateMessageFolder objects for the folders the user has.
getFolder PrivateMessageFolder Returns the specified folder for a user.
createFolder PrivateMessageFolder Creates a new folder.
deleteFolder void Deletes a folder.
getMessage PrivateMessage Returns the specified private message.
createMessage PrivateMessage Creates a new private message.
saveMessageAsDraft void Saves a message as a draft by storing it in the sender's <tt>Drafts</tt> folder.
sendMessage void Sends a private message to another user.

ProfileService

Provides a webservice for managing user's, avatar's, and status levels.

Field Type Description
getUser User Returns a user by its id.
getUserByUsername User Returns a user by its username.
updateUser void Used to update user information in the system.
createUser User Create a new user.
deleteUser void Delete the user with the specified id.
getUserProperties Property Return all extended properties for the user with the specified id.
setUserProperty void Set an extended property for a user.
deleteUserProperty void Delete an extended property from a user.
getUserCount int Returns the number of users in the system.
getUsersBounded User Returns the IDs of users begining at startIndex and until the number results equals numResults.
getUsers User Returns the IDs of the first 1000 users.
getUserByEmailAddress User Returns a user object corresponding to the email address given.
getUsersByEmailAddress User Returns an array user objects corresponding to the email address given.

SystemPropertiesService

Provides a web service for managing Jive System Properties.

Field Type Description
getProperties Property Obtains all Jive System Properties.
saveProperty void Saves a name/value pair as a Jive System Property.
deleteProperty void Deletes a Jive System Property.

WatchService

A service for manipulating a user's watches on objects.

Field Type Description
getDeleteDays int Returns the number of days that a watched object can remain inactive before
watches on that object are deleted.
setDeleteDays void Sets the number of days that a watched object can remain inactive before
watches on that object are deleted.
createUserWatch Watch Create a watch on a user for the specified user.
createThreadWatch Watch Create a watch on a thread for the specified user.
createForumWatch Watch Create a watch on a forum for the user with the specified ID.
createCategoryWatch Watch Create a watch on a category for the specified user.
getForumWatchCount int Return the count of all thread watches in a particular forumID for the given user.
getCategoryWatchCount int Return the count of all forum watches in a particular categoryID for the given userID.
getTotalWatchCount int Returns a count of all watches that a userID has of a particular type.
getWatchList Watch Returns an array of Watch objects for a particular object type that the given user
is watching.
getForumWatches long Returns an array of IDs for the threads a user is watching in a forum.
getCategoryWatches long Returns an array of IDs for all the forum objects a user is watching in a category.
getUserWatch Watch Returns a watch on a particular user, or null if there isn't a watch.
getThreadWatch Watch Returns a watch on a particular thread, or null if there isn't a watch.
getForumWatch Watch Returns a watch on a particular forum, or null if there isn't a watch.
getCategoryWatch Watch Returns a watch on a particular category, or null if there isn't a watch.
isCategoryWatched boolean Returns true if the user is watching the specified category.
isForumWatched boolean Returns true if the user is watching the specified forum.
isThreadWatched boolean Returns true if the user is watching the specified thread.
isUserWatched boolean Returns true if the user is watching the specified user.
deleteWatch void Delete the specified watch.
deleteWatches void Deletes all watches that a user has.
getWatchers User Returns the Users who are watching the specified object.

Permission Values

Value Description
0x000000000000000 No Permssion
0x100000000000000 Permission to see the online status of a particular user.
0x200000000000000 Permission to administer a particular user.
0x400000000000000 Permission to administer a particular group.
0x800000000000000 Permission to administer the entire sytem.
0x1000000000000000 Custom permission 1. Custom permissions are values reserved for use by end-users to implement custom permission behavior.
0x2000000000000000 Custom permission 2.
0x4000000000000000 Custom permission 3.
0x8000000000000000 Custom permission 4.
0x001 Permission to read a forum.
0x002 Permission to create new messages.
0x004 Permission to create new threads.
0x008 Permission to add attachments to messages.
0x010 Permission to create polls.
0x020 Permission to create private messages.
0x040 Permission to rate messages.
0x080 Permission to moderate threads.
0x100 Permission to administer a particular forum.
0x200 Permission to administer a category.
0x400 Permission to vote in a poll.
0x800 Permission to create attachments in private messages.
0x1000 Permission to create, delete, and schedule announcements.
0X2000 Permission to create and delete avatars.

Back to Services

Client API Examples

Jive Software provides a Java client API. The entry point to the client API is the class com.jivesoftware.forum.webservices.ServiceLocator. The ServiceLocator handles authentication and provides getters for all of the Services.

Below are a few example of how to use the client API to connect to the Jive Forums service and perform various tasks. Note, most connections use the HTTPS protocol. We recommend this approach as it's the most secure. The system can be configured to use plain HTTP connections. For descriptions of the various service objects below, see the \#Services.

Also note, some Java examples use JDK 1.5 syntax (foreach loop, Generics). This is just for example purposes as the client API will work on JDK 1.4 or better.

Acquire the Root Forum Category

ServiceLocator locator = new ServiceLocator("https://myforums.com", "admin", "password");
ContentService contentService = locator.getContentService();
ForumCategory forumCategory = contentService.getForumCategory(1);
      

Create a New Thread

ServiceLocator locator = new ServiceLocator("https://myforums.com", "admin", "password");
ContentService contentService = locator.getContentService();
ProfileService profileService = locator.getProfileService();
       
// We want this thread to appear in the forum with ID 33
Forum forum = contentService.getForum(33);
       
// Get the user we want to post the message as
User user = profileService.getUser("myUsername");
       
// Create the thread
ForumThread thread = contentService.createThread("My Test Message", 
    "My message body", forum.getID(), user.getID());
      

Add a Reply to a Message

// The message to reply tolong messageID = 1221;
// The user we're posting the message as long userID = 12123;
ServiceLocator locator = new ServiceLocator("https://myforums.com", "admin", "password");
ContentService contentService = locator.getContentService();
       
// Create the replyForumMessage reply = contentService.createReplyMessage("my subject", 
    "my response", message, userID);
      

Add an Attachment to a Message

// The message we're going add an attachment to 
long messageID = 12123;
       
// Create a FileDataSource for the attachment. Do this with a DataSource object
// (part of the Java Activation Framework)
javax.activation.DataSource myData = new javax.activation.FileDataSource("/home/me/myfile.doc"); 
ServiceLocator locator = new ServiceLocator("https://myforums.com", "admin", "password");
ForumMessageService svc = locator.getForumMessageService();
svc.addAttachmenToMessage("myfile", myData, messageID);
      

Create a New User

ServiceLocator locator = new ServiceLocator("https://myforums.com", "admin", "password");
ProfileService svc = locator.getProfileService(); 
User user = svc.createUser("johnsmith", "password", "johns@foo.com");
      

Get First 1000 Messages in a Thread

ServiceLocator locator = new ServiceLocator("https://myforums.com", "admin", "password");
ForumMessageService messageService = locator.getForumMessageService();
long myThreadID = 333L;
ArrayList<ForumMessage> messages = new ArrayList<ForumMessage>();
long[] messageIDs = messageService.getMessageIDsByThreadID(myThreadID);
for (long messageID : messageIDs) 
{ 
    ForumMessage current = messageService.getForumMessage(messageID); 
    messages.add(current); 
}
      

Execute a Search

ServiceLocator locator = new ServiceLocator("https://myforums.com", "admin", "password");
ContentService service = locator.getContentService(); 
Query query = new Query(); 
query.setQueryString("database java"); 
query.setAfterDate(new GregorianCalendar(2006, 1, 1).getTime()); 
       
// Anything later than Jan 1, 2006
query.setSortField(Query.DATE);
query.setSortOrder(Query.ASCENDING);
       
// Only grab the first 100 entries
long[] messageIDs = service.messageSearch(query, 1, 100);
      

Grant a Specific Group Read Permission to a Specific Forum

long myForumID = 3333L; 
ServiceLocator locator = new ServiceLocator("https://myforums.com", "admin", "password");
GroupService groupService = locator.getGroupService(); 
PermissionService permissionService = locator.getPermissionService(); 
Group group = groupService.getGroup("myGroup");
permissionService.addForumPermissionToGroup(com.jivesoftware.forum.ForumPermissions.READ_FORUM,
    true, group.getID(), myForumID);