com.jivesoftware.community
Interface ReadTracker

All Superinterfaces:

JiveManager

public interface ReadTracker
extends JiveManager

A way to 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:

• UNREAD -- the object has never been read. In a skin, a "new" icon should be used for objects in this state.
• 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.
• 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()

Field Summary

static int	DEFAULT_TRACKING_THRESHOLD_DAYS Default value used to determine number of days old a thread can be before being marked as read.
static int	READ Status to indicate that the object has been read.
static int	UNREAD Status to indicate that the object has never been read.
static int	UPDATED Status to indicate the object has been updated since the last time a read was done.

Method Summary

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, Community community) Returns the count of unread messages that the user has in the community.
JiveIterator<ForumMessage>	getUnreadMessages(User user, Community community) Returns an iterable for the unread messages in the community.
int	getUnreadThreadCount(User user, Community community) Returns the count of unread threads that the user has in the community.
JiveIterator<ForumThread>	getUnreadThreads(User user, Community community) 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, Community community) Marks an entire community as read up until the current instant in time.
void	markRead(User user, ForumMessage message) Marks an individual message as read.
void	setReadTrackingEnabled(boolean enabled) Enables or disables the read tracking feature.

Methods inherited from interface com.jivesoftware.community.JiveManager

destroy, initialize

Field Detail

DEFAULT_TRACKING_THRESHOLD_DAYS

static final int DEFAULT_TRACKING_THRESHOLD_DAYS

Default value used to determine number of days old a thread can be before being marked as read.

See Also:

Constant Field Values

UNREAD

static final int UNREAD

Status to indicate that the object has never been read.

See Also:

Constant Field Values

UPDATED

static final int UPDATED

Status to indicate the object has been updated since the last time a read was done. For example, if a new message is added to a thread.

See Also:

Constant Field Values

READ

static final int READ

Status to indicate that the object has been read.

See Also:

Constant Field Values

Method Detail

isReadTrackingEnabled

boolean isReadTrackingEnabled()

Returns true if read tracking is enabled, false otherwise.

Returns:

true if read tracking is enabled, false otherwise.

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.

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,
              Community community)

Marks an entire community 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.

community - the community to mark as read.

getUnreadThreadCount

int getUnreadThreadCount(User user,
                         Community community)

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.

community - the community to check unread threads in.

Returns:

the number of unread threads in the community.

getUnreadThreads

JiveIterator<ForumThread> getUnreadThreads(User user,
                                           Community community)

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.

community - the community to check unread threads in.

Returns:

an iterable for the unread threads in the community.

getUnreadMessageCount

int getUnreadMessageCount(User user,
                          Community community)

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.

community - community the community to check unread messages in.

Returns:

the number of unread messages in the community.

getUnreadMessages

JiveIterator<ForumMessage> getUnreadMessages(User user,
                                             Community community)

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.

community - the community to check unread messages in.

Returns:

an iterable for the unread messages in the community.