Collaborative Services API

LotusCollaborative Services provide Java API methods and tags for JavaServer Pages (JSP files) for extending the functionality of collaborative portlets such as the Dominoand Extended Products Portlets, People Finder, and the Common Mail portlet.


Collaborative Services defined

Collaborative Services are a set of methods and JavaServer Page tags that allow developers who are writing portlets for WebSphere Portal or other application servers to add Lotus collaborative functionality to their portlets. The services may be used to develop new custom portlets, or to add collaborative functionality (for example, menus or person links indicating online status) to existing portlets.

The services are designed to provide naming, authentication, portal and custom services for portlets that use the Domino and Extended products configured for the portal. As such, the methods provided by the services complement - not replace - the APIs of the individual Domino and Extended products such as the Domino Java API.

Application developers using Collaborative Services can design and implement functional extensions in portlets that incorporate the features of Domino and Extended Products.


Benefits of Collaborative Services

The services provide standardized access to applications, easy-to-use APIs that are optimized for a collaborative portal, and a consistent security model across all Domino and Extended products.

The services enhance many aspects of operation of a collaborative portal site, including:

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

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

In addition, because the services hide the configuration details of the Domino and Extended products that are installed within an enterprise, collaborative functionality can be added to a portlet in a generic way - regardless of the physical requirements and machine-dependent details of portal configuration.


Details of operation

The Collaborative Services program runs in the cs.jar file in the following location:

The program is configured through the CSEnvironment.properties file in the following location:

The Collaborative Services program also requires configuration changes to the CSEnvironment.properties file.


Java objects and tags provided

Collaborative Services comprise the following Java infrastructure objects and service objects:

The services also provide certain tag language descriptors, most importantly the Person tag used for people awareness, including Lotus Sametime functionality.


Infrastructure objects

The following infrastructure, or helper, objects support the Collaborative Services 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 Domino and Extended Products that are installed and enabled to work with WebSphere Portal. Collaborative Services are administered through configuration settings in WebSphere Portal. In addition, the portal administrator may edit certain configuration settings for Collaborative Services manually in the CSEnvironment.properties file. The portal administrator may use either or both of these resources to control the portal environment configuration for Domino and Extended Products servers.


Server Type constants

Server Type constants are used for retrieving configuration information for a specific Domino and Extended product. 

public final static String CS_SERVER_WEBSPHERE_PORTAL_EXTEND
public final static String CS_PERF_PROP_USEWMM
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. When set to true, it attempts to limit the number of LDAP calls needed and thereby boost performance of person links developed with Collaborative Services.


Server Property Name constants

Server Property Name constants are used when retrieving configuration information about a specific Domino and Extended 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 Services 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);

This object provides the following methods: 

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 file that renders the portlet.


Service Type constants

Service Type constants are used when constructing a service object. 

public final static String DOMINO_SERVICE


Methods

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

CSFactory.getService(CSCredentials credentials, String serviceType)

This method is used when you want 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 want 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 Services 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 Collaborative Services. Refer to the Collaborative Services Javadoc HTML documentation for all details on the components of these service objects.

In addition, see the CSEnvironment.properties file for a complete description of the settings that supply values to these APIs. The CSEnvironment properties file is located in...


DominoService

The Domino Service is a set of methods that provide standardized access to Domino releases 4.6 and later, making Domino release 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, such as data from Notes views and capabilities for selection of data in databases.


SametimeService

The Sametime Service is a set of methods that provide standardized access to the Lotus Sametime server configured to work with WebSphere Portal. The methods manage and display contact lists for chat and collaboration. 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 Instant Messaging server. This connection exists for the sole purpose of obtaining Sametime Instant Messaging authentication tokens for users. The tokens are then used to log users into Sametime Instant Messaging from their web browsers.


Person tag

The Collaborative Services include a JavaServer Page tag language descriptor (TLD) for a person tag.

When added to custom portlet, the person tag causes people's names to appear as hyperlinks, and the Click for Person Card option to display when the user moves the cursor over an active (underlined) person's name. Clicking this option displays the Person card. If WebSphere Portal cannot identify the person name, it displays the name as plain text and the Click for Person Card option is not available.

By default, the Person card includes the action Profile. The Send Mail action displays if the user has an email address. If Lotus Sametime is installed and enabled to work with the portal, the person tag adds an icon that indicates the person's online status and additional actions:

The person tag provides only default actions, but you can add own custom actions to the person menu in any portlet.

You can configure the amount of time that the Person card displays by modifying the personTagTimeout custom property.

You can also customize the Person card so that only the business card fields display by default, letting users choose whether to expand the information shown.

The tag library for Collaborative Services that includes the person tag is installed on the portal server in the following locations:

Keep in mind that there is no need to copy or move the .tld file anywhere within the portal project; you need only refer to its location in the portal installation. You need a reference to it in the JSP file for every portlet you deploy that uses the person tag. In addition, because the person tag generates HTML, it requires Java and JavaScript to be enabled on the client.


Parent

Develop portlets
People awareness

 


+

Search Tips   |   Advanced Search