com.jivesoftware.community
Interface ReadTrackerManager

All Superinterfaces:

JiveManager

public interface ReadTrackerManager
extends JiveManager

Manages objects that track the read status of forum threads and messages. Note, this does not cover blogs, blog posts or wiki documents.

This feature is optional in that other Jive classes do not call this API. Instead, the UI layer must explicitly check and mark messages as read or unread. Because there is potentially a high overhead associated with this feature:

• This feature is intended for thousands of users, not tens or hundreds of thousands.
• All messages and threads with a modified date older than a specified time window (default of 30 days) are assumed to be read.

To implement this feature, a skin author must manually mark each message as read as appropriate. For example, in a threaded view, this would be on the page that displays the message. In a flat view where many messages are show on each page, the markRead method should be called for each message on the page. There is no need to mark threads as read since that information can be automatically determined from which messages are read.

There are three states that each thread or message can be in:

• ReadTracker.UNREAD -- the object has never been read. In a skin, a "new" icon should be used for objects in this state.
• ReadTracker.UPDATED -- the object has been read previously, but there have since been updates. In a skin, an "updated" icon should be used for objects in this state.
• ReadTracker.READ -- the object has been read and there have been no updates to it since.

To set a custom time window (in number of days), set the Jive property readTracker.timeWindow. If no property is set, the default value of 30 days will be used.

See Also:

JiveContext.getReadTracker()

Method Summary

void	deleteUserReadTrackers(User user) Deletes a given user's read trackers from the system.
boolean	getReadStatus(JiveContainer c, User user, int type) Returns true if the user has the specified read status on the object, false otherwise.
int	getReadStatus(User user, ForumMessage message) Returns the read status on the specified message.
int	getReadStatus(User user, ForumThread thread) Returns the read status on the specified thread.
int	getUnreadMessageCount(User user, JiveContainer container) Returns the count of unread messages that the user has in the community.
JiveIterator<ForumMessage>	getUnreadMessages(User user, JiveContainer container) Returns an iterable for the unread messages in the community.
int	getUnreadThreadCount(User user, JiveContainer container) Returns the count of unread threads that the user has in the community.
JiveIterator<ForumThread>	getUnreadThreads(User user, JiveContainer container) Returns an iterable for the unread threads in the community.
boolean	isReadTrackingEnabled() Returns true if read tracking is enabled, false otherwise.
void	markRead(User user, ForumMessage message) Marks an individual message as read.
void	markRead(User user, JiveContainer container) Marks an entire continer as read up until the current instant in time.
void	setReadTrackingEnabled(boolean enabled) Enables or disables the read tracking feature.

Methods inherited from interface com.jivesoftware.community.JiveManager

destroy

Method Detail

setReadTrackingEnabled

void setReadTrackingEnabled(boolean enabled)
                            throws UnauthorizedException

Enables or disables the read tracking feature.

Parameters:

enabled - true to enable read tracking, false otherwise.

Throws:

UnauthorizedException - if the user is not a system admin.

isReadTrackingEnabled

boolean isReadTrackingEnabled()

Returns true if read tracking is enabled, false otherwise.

Returns:

true if read tracking is enabled, false otherwise.

getReadStatus

int getReadStatus(User user,
                  ForumThread thread)

Returns the read status on the specified thread.

Parameters:

user - the user reading the thread.

thread - the thread to check read status on.

Returns:

the read status of the thread.

getReadStatus

int getReadStatus(User user,
                  ForumMessage message)

Returns the read status on the specified message.

Parameters:

user - the user reading the message.

message - the message to check read status on.

Returns:

the read status of the message.

markRead

void markRead(User user,
              ForumMessage message)

Marks an individual message as read. This will automatically update the read status of the message's thread.

Parameters:

user - the user that read the message.

message - the message that should be marked as read.

markRead

void markRead(User user,
              JiveContainer container)

Marks an entire continer as read up until the current instant in time. This method is useful if a user wants to "catch up". Note this marks any forum content as read, not content like blogs or wiki documents.

Parameters:

user - the user marking the community as read.

container - the container to mark as read.

deleteUserReadTrackers

void deleteUserReadTrackers(User user)

Deletes a given user's read trackers from the system.

Parameters:

user - the owner of the read trackers being deleted.

getUnreadThreadCount

int getUnreadThreadCount(User user,
                         JiveContainer container)

Returns the count of unread threads that the user has in the community. Threads with a status of UPDATED count as unread for the purposes of this method.

Parameters:

user - the user to check unread threads for.

container - the container to check unread threads in.

Returns:

the number of unread threads in the container.

getUnreadThreads

JiveIterator<ForumThread> getUnreadThreads(User user,
                                           JiveContainer container)

Returns an iterable for the unread threads in the community. Threads with a status of UPDATED count as unread for the purposes of this method.

Parameters:

user - the user to check unread threads for.

container - the container to check unread threads in.

Returns:

an iterable for the unread threads in the container.

getUnreadMessageCount

int getUnreadMessageCount(User user,
                          JiveContainer container)

Returns the count of unread messages that the user has in the community. Messages with a status of UPDATED count as unread for the purposes of this method.

Parameters:

user - user the user to check unread messages for.

container - the container to check unread messages in.

Returns:

the number of unread messages in the community.

getUnreadMessages

JiveIterator<ForumMessage> getUnreadMessages(User user,
                                             JiveContainer container)

Returns an iterable for the unread messages in the community. Messages with a status of UPDATED count as unread for the purposes of this method.

Parameters:

user - user the user to check unread messages for.

container - the container to check unread messages in.

Returns:

an iterable for the unread messages in the community.

getReadStatus

boolean getReadStatus(JiveContainer c,
                      User user,
                      int type)

Returns true if the user has the specified read status on the object, false otherwise.

Note, if the user is a guest then false will be returned always. This is because read tracking is not supported for guests.

Parameters:

user - the user to test

c - the container to check read status in.

Returns:

true if the user has the read status on the given object, false otherwise.