Jive Forums API (5.5.20.2-oracle) Developer Javadocs

com.jivesoftware.forum
Interface ReadTracker

All Known Implementing Classes:
DbReadTracker, ReadTrackerProxy

public interface ReadTracker

Provides optional tracking of the messages and threads that each user has read. This feature is optional in that other Jive Forums 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:

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:

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:
ForumFactory.getReadTracker()

Field Summary
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, Forum forum)
          Returns the count of unread messages that the user has in the forum.
 int getUnreadMessageCount(User user, ForumCategory category)
          Returns the count of unread messages that the user has in the category.
 java.util.Iterator getUnreadMessages(User user, Forum forum)
          Returns an iterator for the unread messages in the forum.
 java.util.Iterator getUnreadMessages(User user, ForumCategory category)
          Returns an iterator for the unread messages in the category.
 int getUnreadThreadCount(User user, Forum forum)
          Returns the count of unread threads that the user has in the forum.
 int getUnreadThreadCount(User user, ForumCategory category)
          Returns the count of unread threads that the user has in the category.
 java.util.Iterator getUnreadThreads(User user, Forum forum)
          Returns an iterator for the unread threads in the forum.
 java.util.Iterator getUnreadThreads(User user, ForumCategory category)
          Returns an iterator for the unread threads in the category.
 boolean isReadTrackingEnabled()
          Returns true if read tracking is enabled, false otherwise.
 void markRead(User user, Forum forum)
          Marks an entire forum as read up until the current instant in time.
 void markRead(User user, ForumCategory category)
          Marks an entire category 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.
 

Field Detail

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,
              Forum forum)
Marks an entire forum as read up until the current instant in time. This method is useful if a user wants to "catch up"

Parameters:
user - the user marking the forum as read.
forum - the forum to mark as read.

markRead

void markRead(User user,
              ForumCategory category)
Marks an entire category as read up until the current instant in time. This method is useful if a user wants to "catch up"

Parameters:
user - the user marking the forum as read.
category - the category to mark as read.

getUnreadThreadCount

int getUnreadThreadCount(User user,
                         Forum forum)
Returns the count of unread threads that the user has in the forum. Threads with a status of UPDATED count as unread for the purposes of this method.

Parameters:
user - the user to check unread threads for.
forum - the forum to check unread threads in.
Returns:
the number of unread threads in the forum.

getUnreadThreadCount

int getUnreadThreadCount(User user,
                         ForumCategory category)
Returns the count of unread threads that the user has in the category. Threads with a status of UPDATED count as unread for the purposes of this method.

Parameters:
user - the user to check unread threads for.
category - the category to check unread threads in.
Returns:
the number of unread threads in the category.

getUnreadThreads

java.util.Iterator getUnreadThreads(User user,
                                    Forum forum)
Returns an iterator for the unread threads in the forum. Threads with a status of UPDATED count as unread for the purposes of this method.

Parameters:
user - the user to check unread threads for.
forum - the forum to check unread threads in.
Returns:
an iterator for the unread threads in the forum.

getUnreadThreads

java.util.Iterator getUnreadThreads(User user,
                                    ForumCategory category)
Returns an iterator for the unread threads in the category. Threads with a status of UPDATED count as unread for the purposes of this method.

Parameters:
user - the user to check unread threads for.
category - the category to check unread threads in.
Returns:
an iterator for the unread threads in the category.

getUnreadMessageCount

int getUnreadMessageCount(User user,
                          Forum forum)
Returns the count of unread messages that the user has in the forum. 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.
forum - forum the forum to check unread messages in.
Returns:
the number of unread messages in the forum.

getUnreadMessageCount

int getUnreadMessageCount(User user,
                          ForumCategory category)
Returns the count of unread messages that the user has in the category. 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.
category - category the forum to check unread messages in.
Returns:
the number of unread messages in the category.

getUnreadMessages

java.util.Iterator getUnreadMessages(User user,
                                     Forum forum)
Returns an iterator for the unread messages in the forum. 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.
forum - forum the forum to check unread messages in.
Returns:
an iterator for the unread messages in the forum.

getUnreadMessages

java.util.Iterator getUnreadMessages(User user,
                                     ForumCategory category)
Returns an iterator for the unread messages in the category. 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.
category - forum the category to check unread messages in.
Returns:
an iterator for the unread messages in the category.

Jive Forums Project Page

Copyright © 1999-2006 Jive Software.