Web Content Management API Best Practices 

• Always use the wcm:initworkspace tag to obtain the Web Content Management API workspace for the current user, as the initworkspace tag will automatically cache the users workspace in the session which improves performance and, when using the Local Rendering Portlet (LRP), performance is further improves since the LRP will populate the cached workspace itself.
  
  Eg: Workspace usersWorkspace = (Workspace) pageContext.getAttribute(Workspace.WCM_WORKSPACE_KEY);

• When obtaining the Web Content Management API Workspace for the ‘System’ or users other than the current user, you should cache the ‘Workspace’ in the session to improve performance. Creating a workspace for a user is slow because Web Content Management needs to pre-calculate the user’s permissions. Caching the Workspace speeds up the rest of the API operations.

See example: How to cache the Web Content Management API Workspace

 

• Use the following code to retrieve a reference to the current rendered or edited content
  
  RenderingContext renderingContext = (RenderingContext) pageContext.getRequest().getAttribute(Workspace.WCM_RENDERINGCONTEXT_KEY);
  Content theContent = renderingContext.getContent(); 

• Call Workspace.login and Workspace.logout around all Web Content Management API method calls that will run within the current request 
• Requires PK50703 for 6.0.1.1 (see iFix readme for correct usage)
• For Multi-Threaded applications, you will need to call login/logout per threadFor long running applications, you will need to periodically re-login to maximize performance (for example, Before the session timeout occurs)

Example:
try
{
    Perform Login
    Workspace.login()

    Call WCM API method cals for current request
    ...
}
finally
{
    Perform logout
    Workspace.logout()
}

 

• Put common functionality into utility JSP files and use jsp:include tags to integrate them. This componentizes your JSP files; you change common functionality in one place once, and then all your JSP files that use that functionality are updated automatically.

• JSP files used by Web Content Management JSP components need to be copied to the following locations:
• Web Content Management WAR directory (for Servlet-Rendering, previewing as a Web page and previewing/rendering in the Remote Rendering Portlet)
• Local Rendering Portlet WAR directory (for previewing/rendering in the Local Rendering Portlet)
• NOTE 1: Whenever the Local-Rendering Portlet or the Workplace Web Content Management Application is updated, then any custom deployed JSPs will be removed and need need to be recopied into place.
• NOTE 2: JSP files used by Web Content Management JSP components are not syndicated, so you need to ensure that they manually copied to any Subscriber servers.

• Use the getComponentByReference() method instead of getComponent() when retrieving components you are not going to edit or add to another container, to improve performance. The getComponent() clones/copies the underlying content component, which is an expensive operation if you only want to read some information off the content component.
  



• 6.0.1.4+ If retrieving documents for read-only purposes ( say in rendering), use the Workspace.getById(, true) method to improve performance. Like the getComponentByReference method above, the 'true' parameter stops WCM from cloning/copying the underlying document.

• 6.0.1.4+ If you need to retrieve many documents, then rather than making repeated calls to Workspace.getById, use the Workspace.getByIds method which takes a DocumentIdIterator. The second method is faster as it results in less trips to the underlying database. The Workspace.createDocumentIdIterator method can be used to manually create a DocumentIdIterator if required.
  

• When using the API from JSPs not managed by Workplace Web Content Management (i.e., those not referenced from Web Content Management JSP Components and Web Content Management Authoring Launch Pages), you should always call the Repository.endWorkspace() method after the JSP has finished processing a request.
• This is because the endWorkspace method is somewhat of a misnomer in that it doesn’t actually close a user’s workspace but rather tells Web Content Management that the current request is complete. Web Content Management then executes various “end request” session management cl ean-up routines.

• Use the setCurrentDocumentLibrary method to make calls library-specific
• 6.0.0.0, 6.0.0.1, 6.0.1: If not specified, then the default library specified in the WCMConfigService.properties file is used.
• 6.0.1.1+: If not specified, then the current rendering or authoring library is used, and if the current rendering/authoring library isn’t available (or the JSP is rendering outside Web Content Management) then the default library specified in the WCMConfigService.properties file is used
• When using setCurrentDocumentLibrary to make calls library-specific, you should store the previously selected document library and restore it and the end of your JSP

Example:

DocumentLibrary currentAPILibrary = null;
try
{
    currentAPILibrary = usersWorkspace.getCurrentDocumentLibrary();
}
catch (NullPointerException npe)
{
    Ignore
}

try
{
    usersWorkspace.setDocumentLibrary();

    Call WCM API method cals for current request
    ...
}
finally
{
    Restore original API library
    if (currentAPILibrary != null)
   {
       usersWorkspace.setCurrentDocumentLibrary(currentAPILibrary);
   }
}

• Consider caching the results of JSP pages that are not security dependant using servlet-caching or Web Content Management caching to improve performance

• As WCM API DocumentId’s contain workflow status information in them, if you make a change that modifies the workflow status (such as a restart or next-stage), then remember to obtain the updated DocumentId from the target object and not use the old DocumentId. .

• Avoid using the API to build custom menus (as the API code is unlikely to perform as the amount of content increases) but rather use a Workplace Web Content Management menu component and override its behaviour using query string arguments.

• See the 'Menu Search Properties' section in the InfoCenter for more information
  
  Example showing how query string override can be assembled dynamically:

<%
RenderingContext context = (RenderingCon text)request.getAttribute(Workspace.WCM_RENDERINGCONTEXT_KEY);
String currentPath = context.getPath();
String currentLibrary = context.getLibrary().getName();
Map myparams = new HashMap();
myparams.put("SiteAreas", currentLibrary+"/mySite/mySiteArea1,"+currentLibrary+"/mySite/mySiteArea2");
%>

 

• If translated error messages are required for JSP Components, then as the Error Message field (on the JSP Component) doesn’t provide this ability, its recommended that the JSPs used by the JSP Components catch all possible errors/exceptions and th en use standard Java Resource Bundles to provid e translated error messages

• Become familiar with the out-of box functionality to avoid using the Workplace Web Content Management API and JSP files to develop existing function.

• 6.0.1.2+ Use the following code to retrieve the path to a piece of content

Workspace usersWorkspace = (Workspace) pageContext.getAttribute(Workspace.WCM_WORKSPACE_KEY);

String path = usersWorkspace.getPathById(theContentId);

 

• If you have custom code (using the WCM Public API) that resides within its own Enterprise Application, then that application must start after the 'wcm' Enterprise Application has started. Using a starting weight of greater than 50 should work in most releases, but manually checking the starting weight of the 'wcm' application and ensuring that your applications starting weight is greater than this is recommended.

• When creating plugin applications (eg. EARs of custom workflow actions and/or context processors), make sure that the following is unique across the plugin applications (eg. EARs), otherwise if you introduce a second plugin application it will override the first:
• The plugin 'id', plugin 'name' and extension 'id' (but not extension-point 'id') attributes of the plugin.xml.
• Note: For each extension-point type, at least one of the plugin.xml files for that type MUST have a plugin 'id' set to 'com.ibm.workplace.wcm.api' otherwise the extension-point will not be registered with WAS and Portal, which will cause all extensions of that type to be unaccessible. Additionally the application with a plugin 'id' of 'com.ibm.workplace.wcm.api' will has to be started before the rest (and after the wcm.ear).
  
• The fully qualified class name (class name plus path) of all classes within the application
• The file path of any files within the application
  

• Do not call the Repository.endWorkspace() method from within JSPs that will execute within a JSP Component, as doing so will produce the following exception:

java.lang.IllegalStateException: Repository is not logged in.
at com.ibm.workplace.wcm.services.repository.WorkspaceManager.getActiveCredentials
at com.ibm.workplace.wcm.services.repository.WorkspaceManager.logout