Collaboration

A discussion thread or collaboration occurs around a sequence of comments. Each individual comment has a text portion and one or more attachments (usually binary). Each comment maintains the time it was created, the author of the comment and it's contents. A discussion thread maintains the time it was created, the owner/creator and the current list of comments in the thread. The discussion thread is attached to the smart object for which the comments are meant.

Usage Scenarios
Associating remarks with metadata objects
Retrieving comments using filters

Usage Scenarios

Discussion thread on smart object

Here the comments are seen as separate entities - short communications on the topic of the smart object to which they are attached. New comments are added at the end of the list and existing comments are read only. There is no need for an application to manage or interpret the comment text, although one might be provided to format the comments. Comments are generally unstructured and simple text, with possibly some attachments, supporting the basic text in the comment. 

UserContext user2;  // Steven Butcher;
UserContext user1; // Bruce Simons

// Create a new Remarks metadata object
String type = "remarks";
String name = dt.format( new Date() );
remarks = (RemarksInterface)myDocuments.addNewItem( name, type );
remarks.setOwner( user1 );
remarks.setTopic( "General comments" );

comment = new Comment( user2, cText ); 
// Access some binary content for an attachment
FileInputStream image2 = null;
try {
     image2 = new FileInputStream( "c:\\temp\\gchart.gif" );
} catch ( FileNotFoundException fnf ) { fnf.printStackTrace(); }
if ( image2 != null ) comment.addAttachment( "SepSales", "Sales for 2002", "image/gif", image2 );

remarks.addComment( comment );
remarks.update();

Multiple discussion threads on a smart object

It is possible to have multiple discussion threads attached to any metadata object. Apart from the obvious difference in discussion topic, it might be used to allow different communities to comment on the common object.

Application text stored in comments

In this scenario, the comment text is structured and has application defined semantics. For example it might contain a user's comments for all the cells in a table, and the text is parsed to separate comments for individual cells. The application might combine a variety of comment sources before presenting the commentary. In this case, comment text is directly accessible and read/write. Taking this scenario to the extreme it is possible to have all comments by all users in one comment, rather than having separate individual comments.

Remarks on remarks

As the discussion thread is itself a metadata object, it can have remarks attached to it. Here two discussion threads are linked as one is related to the other.

Associating remarks with metadata objects

The method getRemarksList returns a list of Remarks objects (there may be more than one discussion topic related to a particular metadata object). 
Iterator remarks = mi.getRemarksList();
while ( remarks.hasNext() ) {
    remark = (Remarks)remarks.next();
    ...
}

To set remarks on a metadata object add the relevant Remarks object to a List and use the setRemarksList method 
List remarks = new List();
remarks.add( remark );
mi.setRemarksList( remarks );

Retrieving comments using filters

The getComments method takes a comment filter to determine which comments in the discussion thread should be returned. The default comment filter returns all visible comments (ie. all public comments and only those private comments owned by the requester). There are a variety of other comment filter types that can be used.

  1. Owner filter
    All comments, including private comments are returned, if the requester is actually the creator of the discussion thread. 
    CommentFilter filter = new CommentFilter( CommentFilterInterface.OWNER );
Iterator comments = remarks.getComments( filter ).iterator();
  2. Author filter
    Only comments authored by the requester are returned (public and private comments). 
    CommentFilter filter = new CommentFilter( CommentFilterInterface.AUTHOR );
Iterator comments = remarks.getComments( filter ).iterator();
  3. Range filter
    Only comments that satisfy the range are returned. Currently, range filters can be applied to the author, text and timestamp attributes. The first example retrieves comments where the comment text begins with anything less than a "U". 
    CommentFilter filter = new CommentFilter( );
filter.setRangeFilterModifierString( CommentFilterInterface.TEXT_RANGE, null, "U" );
Iterator comments = remarks.getComments( filter ).iterator();
    or, in this example any comments that are time stamped between startDate and endDate are returned. 
    CommentFilter filter = new CommentFilter( );
filter.setRangeFilterModifierLong( CommentFilterInterface.DATETIME_RANGE, 0, 100 );
cf.setRangeFilterModifierLong( CommentFilterInterface.DATETIME_RANGE, startDate.getTime(), endDate.getTime() );
Iterator comments  = remark.getComments( cf ).iterator();