Collaborative Components API

Lotus Collaborative Components provide Java API methods and tags for Java Server Pages (JSPs) for extending the functionality of Lotus advanced collaboration in portlets. Application developers using Collaborative Components can design and implement functional extensions in portlets that incorporate the features of Domino and Notes, Lotus QuickPlace, Lotus Sametime, and Lotus Discovery Server.

Javadoc for Collaborative Components is installed on WebSphere Portal. In addition, more detailed documentation that supplements this information will be available on the WebSphere Portal Family Web site.

The Javadoc for Collaborative Components is available from this WebSphere Portal location:

 class="help"><wp_root>/doc/Javadoc/CollabServices/index.html

You can also deploy standalone samples (JSPs) of Collaborative Components as described in Collaborative Components Samples.

 

Collaborative Components defined

Collaborative Components (also sometimes called "collaborative services" or "cs") are a set of methods and JSP tags that allow developers who are writing portlets for WebSphere Portal or other application servers to add Lotus collaborative functionality to their portlets. Collaborative Components can be used to develop new custom portlets or to add collaborative functionality (menus or people links indicating online status, for example) to existing portlets.

Collaborative Components are designed to provide access to the functionality of Lotus Software products that are enabled to work as companion products to WebSphere Portal. As such, the methods provided by Collaborative Components complement - not replace - the APIs of the individual companion products such as the Domino Java API and the Discovery Server KDSAPI.

 

Benefits of Collaborative Components

Collaborative Components provide standardized access to applications, easy-to-use APIs that are optimized for a collaborative portal, and a consistent security model across all Lotus Software companion products.

All of the Collaborative Components, except the people and menu tags, are user interface-neutral; that is, the portlet developer can design the user interface for the collaborative features they are implementing. The goal of Collaborative Components is to provide the data necessary for rendering the user interface and to allow the developer to execute actions on the Lotus collaborative products that have been installed and enabled in the portal environment.

The Java APIs in Collaborative Components contain no platform-specific code. Consequently, the components are UI-neutral and are not dependent on implementation details. Because they are UI-neutral, the Collaborative Components can be used to implement pervasive applications for mobile and wireless devices.

Because Collaborative Components hide the configuration details of the Lotus products that are installed within an enterprise, collaborative functionality can be easily added to a portlet in a generic way - regardless of the physical requirements and machine-dependent details of portal configuration.

 

Java objects and tags provided

Collaborative Components comprise the following Java infrastructure objects, service objects, and tag language descriptors for custom tags for JSPs:

 

Service object example

Collaborative Components service objects (Java classes) operate in a framework of helper objects that are not themselves service objects but which provide the infrastructure for all service object methods.

The following example illustrates how infrastructure objects construct the QuickPlace service object:

<%
...
CSEnvironment environ = CSEnvironment.getEnvironment(request);
CSCredentials cred = environ.getCredentials(request);
QPService quickplaceService = (QPService)CSFactory.getService(cred, CSFactory.QUICKPLACE_SERVICE);




if (quickplaceService != null)




{




	... (for example, use the quickPlaceService to create QuickPlaces)








	quickplaceService.cleanup();




}




...




%>




In this example, the first object, called CSEnvironment, gets and sets the configuration options of the collaborative portal environment, including the server information for the installed and enabled companion products (for example, Domino Directory, Lotus Sametime, Lotus QuickPlace, and Lotus Discovery Server). For more information, see CSEnvironment object.




The second object, CSCredentials, is required by most of the Collaborative Components methods because it contains the credentials for the each authenticated user (including user, password, and SSO token, if available). User credentials are stored in an HTTP session object and are obtained by the CSEnvironment object, for the method CSEnvironment.getCredentials. For more information, see CSCredentials object.




The service object is created, or constructed, by the third infrastructure object, CSFactory, which instantiates the type of service object called (in this example, QuickPlace). The CSFactory object creates the requested service and initializes a connection with the worker server, the server that handles the service requests for the requested service object (in this example, the QuickPlace server). The object can also maintain the server configuration information for reuse. For more information, see CSFactory object.





Important Each service object requires a call to the cleanup() method at the end of its use.




 

Infrastructure objects





The following infrastructure, or helper, objects support the Collaborative Components service objects (Java classes and methods):








      


CSEnvironment object





The CSEnvironment object is created with the request object as follows:




CSEnvironment environ = CSEnvironment.getEnvironment(request);




The CSEnvironment object provides information about the servers of any Lotus Companion Products, for example Lotus Sametime or Lotus QuickPlace, that are installed and enabled to work with WebSphere Portal.





Note Lotus Collaborative Components are administered through configuration management tools in WebSphere Portal. In addition, the portal administrator can edit certain configuration settings for LCC manually in the CSEnvironment.properties file. The portal administrator can use either or both of these resources to control the portal environment configuration for Lotus companion products servers. For more information, see Planning for collaboration.




While Collaborative Components support Lotus Discovery Server 1.1 and QuickPlace 2.0.8, the APIs assume that the newer versions of Lotus Discovery Server and QuickPlace are installed and in use:




CS_SERVER_DISCOVERY_SERVER_1.version=2.0




CS_SERVER_QUICKPLACE_1.version=3.0




 

Server Type constants





Server Type constants are used for retrieving configuration information for a specific Lotus companion product.




public final static String CS_SERVER_WEBSPHERE_PORTAL_EXTEND




public final static String CS_PERF_PROP_USEWMM




public final static String CS_SERVER_QUICKPLACE




public final static String CS_SERVER_DISCOVERY_SERVER




public final static String CS_SERVER_DOMINO_DIRECTORY




public final static String CS_SERVER_SAMETIME




CS_PERF_PROP_USEWMM is a performance tuning option for the Person tag. It provides a choice of enabling Domino LDAP queries for e-mail addresses instead of WebSphere Member Management (WMM) lookup. Bypassing WMM lookup and preferring an existing Domino LDAP service for search and retrieval of e-mail addresses can significantly boost performance of people links developed with Collaborative Components.






 

Server Property Name constants





Server Property Name constants are used when retrieving configuration information about a specific Lotus companion product server.




public final static String CS_PROP_ENABLED




public final static String CS_PROP_HOSTNAME




public final static String CS_PROP_PROTOCOL




public final static String CS_PROP_VERSION





CSCredentials object





The CSCredentials class (obtained from the CSEnvironment.getCredentials method) is required by most of the Collaborative Components methods because it contains the credentials for the authenticated user: user ID, password, and SSO token, if available.




A CSCredentials object is created as follows:




CSEnvironment environ = new CSEnvironment(request);




CSCredentials cred = environ.getCredentials(request);




Methods provided by this object are the following:




public String getUserLoginName




Returns the name used by the current user to log in to the application.




public String getUserName




Returns the distinguished name for the currently logged in user.

    


CSFactory object





The CSFactory.getService call is responsible for constructing a service object. This results in a connection being established with a worker server. This connection is saved within the service object for reuse in future calls within the JSP that renders the portlet. For example, the QuickPlaceService object is constructed with a specific server. The QuickPlaceService object can then be used to create one or more QuickPlaces on that server.




 

Service Type constants





Service Type constants are used when constructing a service object.




public final static String DISCOVERY_SERVER_SERVICE




public final static String QUICKPLACE_SERVICE




public final static String DOMINO_SERVICE





 

Methods





To construct a Collaborative Components service object,  use one of the following methods:




CSFactory.getService(CSCredentials credentials, String serviceType)




This method is used when you wish to use the server that is configured in the portal environment.




CSFactory.getService(CSCredentials credentials, String serviceType, String server, String protocol)




This method is used when you wish to override either the server that is configured in the environment or a server has not yet been configured in the portal environment.




The getService method returns a Collaborative Components service object, depending on serviceType, for example, CSFactory.DOMINO_SERVICE.



    

 

Summary of collaborative Java service objects





The following Java service objects provide the classes and methods of Lotus Collaborative Components. Refer to the Lotus Collaborative Components Javadoc for details such as parameters and specific return values. 








      


DominoService





The Domino Service is a set of methods that provide standardized access to all versions of Domino from Domino 4.6 through 6.0, making Domino version differences transparent for portal and portlet development. The DominoService objects support any Domino capabilities that are needed for Notes-based repositories that work with the portal. The DominoService methods are many, and they are classified by their function:











Note The Lotus Notes productivity portlets that are installed with WebSphere Portal are not implemented with the DominoService object. Therefore, do not refer to those portlets as examples. Instead, refer to the samples that are installed with the Collaborative Components enterprise application (cs.ear).




Some of the more important methods are described in the following sections.





 

Server methods





java.util.HashMap getServers() 




Returns a list of Domino servers in the domain that have the http-hostname attribute set. 


    


 

Database methods





boolean addACL()




Adds a single ACL to an existing database. 




boolean createDatabase() 




Creates a new Domino database from a database template. 




java.util.HashMap getDatabases() 




Returns a list of Domino database names and directory names in the specified start directory. 


    


 

View methods





ViewInfo getViewInfo() 




Returns view information about a view, encapsulated in a ViewInfo object. 




java.util.HashMap getDatabaseViews() 




Returns a list of views in a specified Domino database. 


    
    


 

User Name and Person information methods





java.lang.String getDistinguishedName() 




Returns the distinguished name of the user. 




java.lang.String getDominoName() 




Converts a distinguished name into a Domino name (also referred to as the Abbreviated name) For example, "OU=Acme,O=Sales" is converted to "/Acme/Sales"





Note This is simply a helper method - there is no LDAP query made. 




java.lang.String getEmailAddress() 




Returns the e-mail address of the user. 




java.lang.String[] getMailServerFile() 




Returns the names of the Domino mail database file and mail server for a valid user in the domain. 


    
    

    
    


 

Methods related to QuickPlace





java.lang.String[] getQuickPlaceComponents() 




Returns a list of QuickPlace components in a QuickPlace. 




java.lang.String[] getQuickPlaceDatabases() 




Returns the list of QuickPlace databases. 




java.lang.String getCompleteQuickPlaceComponents() 




Returns a list of QuickPlace components in a QuickPlace. 


    
    
    


 

Initialization/Cleanup methods





void init()




Do not call the init() method. 




void cleanup()




Always call the cleanup() method when finished with the Service object.


    
    


QPService





The QuickPlace Service (QPService) is much expanded in this release of Lotus Collaborative Components. It provides the following methods:




public java.util.HashMap getPlacesForMember()




Returns a list of QuickPlaces the authenticated user is a member of on all QuickPlace servers in the QuickPlace service. This method works with QuickPlace 3.0 only.




public java.lang.String create(java.util.Hashtable ht)




Creates a QuickPlace on the remote server and returns the URL that references it. This method works with QuickPlace 2.0.8 and QuickPlace 3.0.




public Vector search()




Performs a full-text search across all QuickPlaces in the QuickPlace service.




public String createPlace()




Creates a QuickPlace on the remote server and returns the URL that references it. The initial QuickPlace manager will be the authenticated user.




public String [] getPlaces()





Retrieves a list of placetypes, with their descriptions, that are available on this server.




public HashMap getPlaceTypes()




Retrieves a HashMap of placetypes, with their descriptions, that are available on this server.




public HashMap [] getMemberAccess()




Returns the distinguished names and access rights of all members and groups to a room of a QuickPlace.




public boolean addMember()




Adds a member and assigns access rights to a room of a QuickPlace.




public boolean addGroup()




Adds a group and assigns access rights to a room of a QuickPlace.




public boolean removeMember()




Removes a member from a room of a QuickPlace.




public boolean removeGroup()




Removes a group from a room of a QuickPlace.




public boolean updateMetaData()




Updates the QuickPlace title and passes in meta data name value pairs. Meta data is stored in the placecatalog under the quickplace name.




public boolean removePlace()




Removes the entire QuickPlace from the server




public boolean lockPlace()




Locks the specified QuickPlace. Access to the QuickPlace is prohibited until the QuickPlace is unlocked.




public boolean unlockPlace()




Unlocks the specified QuickPlace. Access to the QuickPlace is allowed after the QuickPlace is unlocked.




public HashMap getRoomStructure()




Returns a hashmap of all elements of a room in a QuickPlace.




public TreeMap getPlaceStructure()




Returns a treeMap representing the room hierarchy of the QuickPlace.




public boolean doesPlaceExist()




Verifies the existence of a QuickPlace.



    
    
    


PeopleService





The People Service retrieves information about a specified person from the directory configured to work with WebSphere Portal.




public HashMap getPersonInfo





 

Property Name constants





public final static String CS_PERSON_FULLNAME




public final static String CS_PERSON_EMAIL




public final static String CS_PERSON_DOMINONAME




public final static String CS_PERSON_DOMINOMAILSERVER




public final static String CS_PERSON_DOMINOMAILFILE




public final static String CS_PERSON_DEPARTMENT




public final static String CS_PERSON_JOBTITLE




public final static String CS_PERSON_LOCATION




public final static String CS_PERSON_PROFILEURL




public final static String CS_PERSON_SUMMARY




DiscoveryServerService





The Discovery Server Service is a set of methods that provide Discovery Server functionality, specifically the following:










The DiscoveryServerService supports APIs available in Lotus Discovery Server 1.1 and 2.0. APIs for Lotus Discovery Server, formerly known as Knowledge Discovery System (KDS), are available in KDSW.jar and kdsapi.jar. By default, the DiscoveryServerService assumes that Lotus Discovery Server 2.0 is installed and will use the newer API methods. Lotus Discovery Server 1.1 is supported if the version information specified in the CSEnvironment.properties file indicates this version:




CS_SERVER_DISCOVERY_SERVER_1.version=1.1




In this case, the DiscoveryServerService will use the deprecated KDS APIs available in Lotus Discovery Server 1.1.




The following DiscoveryServerService methods vary for different versions of Lotus Discovery Server that are distinguished by a version suffix:




getProfileURL_DS11




GetProfileURL_DS20




Other new DiscoveryServerService methods work only with Lotus Discovery Server 2.0 and are annotated in the Javadoc:




getMetrics




getTaxonomyData




getWorkQueueReader




getWorkQueueWriter




getKMapURL(java.lang.String categoryId)







SametimeService





The Sametime Service is a set of methods that provide standardized access to the Sametime server configured to work with WebSphere Portal.




See the WebSphere\AppServer\lib\app\config\CSEnvironment.properties file for a complete description of the settings that supply values to these APIs.




public String getServer()




Returns the Sametime server hostname, for example, my.server.com.




public String getVersion()




Returns the Sametime server version.




public String getProtocol()




Returns the Sametime server protocol.




public String getFullURL()




Returns the Sametime server's full URL, for example, http://my.server.com:80.




public String getPort()




Returns the Sametime server port.




public String getServerappPort()




Returns the Sametime server application port, which is the port that the Sametime server application should connect through. The default connection is configured to connect through the Sametime mux. If you want to connect directly to the server, set the port explicitly in CSEnvironment.properties.




public String getReconnect()




Returns the Sametime reconnect interval (in seconds), which specifies how often to attempt to reconnect to the Sametime server after being disconnected, or not connected. The default interval of 30 seconds is used when this value is not set.




public String getTimeout()




Returns the Sametime timeout value (in seconds). The timeout is the maximum amount of time to wait for a response from the Sametime server. Without a timeout setting, the internal default of 60 seconds is used.




public String getNameFormat()




Returns the name format to use when resolving the WebSphere Portal authenticated user with the Sametime server.




public String getNameSeparator()




Returns the character to use to separate distinguished names. This character is used when resolving names with the Sametime server, and also for the name used to log in to Sametime from the browser.




public String getUseLTPAToken()




Returns whether to use the LTPA token for logging into Sametime from the browser. If the CS_SERVER_CUSTOM_CRED is enabled and the ssoTokenAttrib is specified, the SSO token is used instead of the LTPA token. By default an internal Sametime token is used. This option should be enabled only if your Sametime server supports tokens produced by WebSphere Portal.




public String getDefaultTimeout()




Returns the internal default Sametime timeout value (in seconds), which is the maximum amount of time to wait for a response from the Sametime server. This value is used only if the timeout is not specified in the CSEnvironment.properties file.




public int helperGetTimeout()




Returns the Sametime timeout value (in milliseconds as an integer), which is the maximum amount of time to wait for a response from the Sametime server. This value is calculated using the timeout specified in the CSEnvironment.properties file, or the default timeout if not specified, and converted into the number of milliseconds as an integer. This value can then be directly used in Java calls that require a time length in that format.




public String getDefaultReconnect()




Returns the internal default Sametime reconnect interval (in seconds), which is how often to attempt to reconnect to the Sametime server after being disconnected, or not connected. This value is used only if the reconnect is not specified in the CSEnvironment.properties file.




public int helperGetReconnect()




Returns the Sametime reconnect interval (in milliseconds as an integer), which is how often to attempt to reconnect to the Sametime server after being disconnected, or not connected. 0 indicates that there should be no attempt to reconnect. 




This value is calculated using the reconnect interval specified in the CSEnvironment.properties file, or the default reconnect interval if not specified, and converted into the number of milliseconds as an integer. This value can then be directly used in Java calls that require a time length in that format.





Note Certain SametimeService methods -- getServerappPort(), getNameFormat(), and getNameSeparator(), and all the "Reconnect" and "Timeout" methods -- pertain to the server-to-server connection between WebSphere Portal and the Sametime server. This connection exists for the sole purpose of obtaining Sametime authentication tokens for users. The tokens are then used to log users into Sametime from their web browsers.



 

Tags examples





Collaborative Components include Java Server Page (JSP) tag language descriptors (TLDs) for custom Person and Menu tags that can be used with certain service objects. The tag libraries for Collaborative Components are installed on WebSphere Portal in this location:




<installation_drive>:PortalServer\shared\app\web-inf\tld\people.tld




<installation_drive>:PortalServer\shared\app\web-inf\tld\people.tld




Keep in mind that there is no need to copy or move the .tld files anywhere within your portal project; you need only refer to their location in your portal installation. You need a reference to them in the JSP for every portlet you deploy that uses them.




To use these tags within your JSP, add the following lines to your page:




<%@taglib uri="/WEB-INF/tld/people.tld"prefix="peopleservice"%>





<%@taglib uri="/WEB-INF/tld/menu.tld"prefix="menu"%>





The following example illustrates how the person tag can be used to provide person link menus for named persons returned by the PeopleService object.




In this example, the bolded portions interact with Lotus Collaborative Components. The first three % statements are references to the LCC tag libraries and classes. The % statement following the <h1> tag is the reference to the LCC infrastructure. And the final % statement uses the LCC person tag to display the user's name as an instant messaging link.




<%@ page language="java" import="com.lotus.cs.*, java.util.*" %>





<%@taglib uri="/WEB-INF/tld/people.tld" prefix="peopleservice" %>





<%@taglib uri="/WEB-INF/tld/menu.tld"prefix="menu"%>





<%@taglib uri="/WEB-INF/tld/portlet.tld" prefix="portletAPI" %>




<portletAPI:init/>




Hello example




<h1>Collaborative Components Hello JSP</h1>




<%





CSEnvironment environ = CSEnvironment.getEnvironment(request);





CSCredentials cred = environ.getCredentials(request);





%>





<BR>




<H2>Hello, <peopleservice:person>





<%=cred.getUserLoginName()%>





</peopleservice:person>!<H2>


    
    


Person tags





The Person (formerly People or People Awareness) tags provide contextual collaboration functionality related to a named person. Use them to generate a link menu of collaborative actions, such as sending e-mail to a named person. The PeopleService tag library contains the tag language descriptors for the following tags:








The Person tags generate HTML and require Java and JavaScript to be enabled on the client.





 

person





Displays person link menu items according to the Lotus companion products for advanced collaboration that are installed and enabled in the portal environment




Added to a person's name string returned by the PeopleService object, the person tag generates the HTML that renders the person link menu that provides the following basic actions for collaborating with the named person:










If Sametime is installed and enabled to work with WebSphere Portal, then the person tag also provides online status for the person link and the following additional actions on the person menu:










If Discovery Server is installed and enabled to work with WebSphere Portal, then the person tag provides the following additional actions on the person menu:










The following example shows how to use the person tag:




<pa:person>John Smith</pa:person>





Because no "value" is specified, the name is used as both the display name and the name to send to Sametime.




The following example shows how to use the person tag with the "value" attribute:




<pa:person value="CN=John Smith,OU=CAM,O=IBM">Smith, John</pa:person>





In this example, the name is used as the display name and the "value" as the name to send to Sametime.

    


 

peopleinit





Determines whether Sametime or Discovery Server, or both, are enabled to work with WebSphere Portal and generates the HTML and JavaScript for initializing Sametime or enabling Discovery Server, or both. Establishes the server connections between WebSphere Portal, the Sametime server, and the Discovery Server, and provides automatic log-in to all servers.





Note The peopleinit tag is included in the HeadInclude.jsp of a collaborative portal; it is not for use inside any portlets.

    



 

peopleend





Finalizes the people functionality.





Note The peopleend tag is included in the PageEndInclude.jsp of a collaborative portal; it is not for use inside any portlets.

    



 

Examples of using person tags to generate names





The display name portion of the person tag (the part between the angle brackets) can be customized so that your portlet shows a value useful to your application. Here are some examples.




The following example, representing the approach taken by the Notes and Domino portlet, generates a common name (cn):




<peopleservice:person> Jane Smith </peopleservice:person>





The following example, representing the approach taken by the Collaboration Center portlets such as People Finder, generates a distinguished name (dn):




<p:person value="cn=jane,ou=smith">Smith,Jane</p:person>





The following example, representing an approach that might be useful in a portlet in a portal where the LDAP server is an IBM Directory Server, also generates a distinguished name (dn):




<p:person value="uid=jsmith,cn=users">Smith,Jane</p:person>





 

Example: Extending the PeopleService menu options globally





A portal (enterprise) developer can add items to the menu that is displayed for all names that are PeopleService enabled in all portlets. For example, in an Acme Corporation Intranet application, you could add a "Show Employee Record" link. This is accomplished by adding a menu called "peoplemenu_more" and some accompanying JavaScript to the HeadInclude.jsp located in




...\wps.ear\wps.war\themes\html\extension





The following example shows the code that adds the menu and sample accompanying JavaScript:




<menu:menucontext contextName="peoplemenu_moreContext">




	<menu:menu menuName="peoplemenu_more" menuID="peoplemenu_more">




		<menu:menuitem itemName="Show Employee Record..." callbackFn="launchPersona();" />




	</menu:menu>




</menu:menucontext>








<SCRIPT>




function launchPersona()




{




	// name (currently in a form like "Jane Doe") needs to be in the form of Doe,Jane




	var names = linkId.split(" "); // linkId contains the name contained within the person tag




	var employeeListURL = "http://employeelist.acme.com/cgi-bin/bluepages.pl?Selection=Name&selectOn=";




	employeeListURL += names[1];




	employeeListURL += ",";




	employeeListURL += names[0];




	window.open(employeeListURL);




}




</SCRIPT>







Menu tags





The Menu tags allow developers to add menus to their Collaborative Components applications. Menus might be associated with mouse events for icons, hrefs, and other UI elements on a portal page. Menu items and associated actions might be defined, and the Resource service might be used to internationalize the menu items. Action code (callback functions) is written in JavaScript.




The Person tags use the Menu tags to display person link menus next to a person's name.




The MenuService tag library contains the tag language descriptors for the following tags:













 

Logging





Collaborative Components use the WebSphere JRAS facility for logging to the WebSphere Administrative Console or to log files.




For Diagnostic Trace, specify the following value to log information related to the Collaborative Components:




 class="help">com.lotus.cs.cslog=all=enabled:com.lotus.ap.portlets.*=all=enabled:com.ibm.wkplc.*=all=enabled




The trace file can be found at this location: 




 class="help"><wp_root>/log/trace.log





 
See also