Mastering WDK Developer Tips and Tricks. A.J. Whitney

Transcription

1 Mastering WDK Developer Tips and Tricks A.J. Whitney Documentum Developer Conference 2004

2 What is this presentation? What this presentation is about Practical tips for WDK developers on topics not covered in the manuals Tips about making WDK development environments faster and more flexible Gotchas that burn most new WDK developers What it isn t about Not a tutorial on WDK Not detailed about specific customizations, components, nor controls Slide 1 of 53

3 Agenda Introductions About Blue Fish Environment Improving the development cycle Project organization/deployment Developing Customizing components Watch what s going on Gotchas Questions Slide 2 of 53

4 Topic Preview - Environment Improving the development cycle Using Jikes to speed JSP compiles Using hot swap code replacement to avoid server restarts Using refresh.jsp to pick up configuration changes Project organization/deployment Tips on how to organize your source tree How to build a developer server pack Slide 3 of 53

5 Topic Preview - Developing Basic WDK Tips Figure out which component to customize Know how to use logging and tracing Gotchas Working around the BOF custom classloader Keeping data dictionary caching from biting you Always have a config directory Don t forget to define parameters Don t throw RuntimeExceptions from actions Understand the DocbaseRoleModel Slide 4 of 53

6 Where are we? Introductions About Blue Fish Improving the development cycle Project organization/deployment Basic WDK Tips Gotchas Questions Slide 5 of 53

7 Blue Fish Development Group Documentum Focus: Complete Documentum Solutions Provider 8+ Years, 100+ projects experience Select Services Team (SST), Signature Services Partner Product Advisory Committee dm_developer ( Core Services: CM Strategy Planning & Analysis Data & Content Migrations Web Content Management Traditional EDMS Product offerings: DIXI Blue Fish API Slide 6 of 53

8 Blue Fish Development Group A partial client list: Bristol-Myers Squibb Sun Microsystems Halliburton Centers for Disease Control ExxonMobil RealNetworks Sara Lee TotalFinaElf Southwest Airlines Documentum Slide 7 of 53

9 Things that Matter about Blue Fish Documentum experts and thought leaders dm_developer ( Business focus Total systems perspective Proven methodology and tool set Fixed-bid implementation approach mitigates risk Flexible engagement approach We re easy to work with Slide 8 of 53

10 Where are we? Introductions About Blue Fish Improving the development cycle Project organization/deployment Basic WDK Tips Gotchas Questions Slide 9 of 53

11 Improving the development cycle Micro development cycle 1. Code compile deploy 2. Restart server login navigate test 3. Repeat With J2EE web-based applications (especially WDK-based applications) this cycle is slow Step #1 typically takes only a few seconds Step #2 may take a tedious minute or two We ll look at three ways to shorten #2 Slide 10 of 53

12 Using Jikes to speed page compiles Jikes is a native Java compiler Precompiling also an option (but more involved) Jasper requires you to have a version of Jikes that supports the encoding option but the prebuilt EXEs from IBM do not support encoding Download a version supporting encoding from Add jikes.exe to your path Slide 11 of 53

13 Update the default web.xml Update the default web.xml: %CATALINA_HOME%/conf/web.xml Slide 12 of 53

14 Update the web.xml in your web app The web.xml shipping with Webtop, Web Publisher, or Documentum Administrator may define the JSP-Compiler servlet. Remove it (and the *.jsp servlet-mapping). {webapp}/web-inf/web.xml Slide 13 of 53

15 JSP compilation error using javac Slide 14 of 53

16 Same compilation error with Jikes Slide 15 of 53

17 Hot swap code replacement Allows you to change code on the fly in your local IDE and have those changes immediately reflected on the server (which may or may not be running on the same machine) without a server restart A function of the Java Platform Debugging Architecture (JPDA) in Java 1.4.x Slide 16 of 53

18 Using hot code replace Hot code replace is supported on Sun JDK 1.4.x VMs and IBMR J9 VMs. Hot code replace is limited to changes which do not effect the shape of a class. That is, changes within existing methods are supported, but the addition or removal of members is not supported. Hot code replace and stepping on JDK VMs is unreliable. Slide 17 of 53

19 Configuring JVM for debugging In order to support debugging, the following parameters need to be passed to the virtual machine (Sun s JDK 1.4) -Xdebug -Xrunjdwp:transport=dt_socket, address=4000, server=y,suspend=n The transport and address may be set to other values (for example) transport=dt_shmem address=myapp Slide 18 of 53

20 Setting tomcat up for debugging Set the JDPA_TRANSPORT and JPDA_ADDRESS environment variables Or, update catalina.bat to set the transport and address Start tomcat with catalina.bat jpda run Slide 19 of 53

21 Attach with your debugger Attach with your debugger and run your code Running with a debugger attached is very fast in modern VMs Slide 20 of 53

22 Using refresh.jsp Reloads the WDK configuration files without bouncing the server or requiring a login Useful when components are configuration-driven based on data loaded from the WDK configuration files Slide 21 of 53

23 Where are we? Introductions About Blue Fish Improving the development cycle Project organization/deployment Basic WDK Tips Gotchas Questions Slide 22 of 53

24 Project organization and deployment WDK projects are composed of lots of files A component has at least four parts XML configuration file Java source for the component At least one JSP page At least one NLS bundle Typically you are working on all of the pieces together Traditionally, each of these component parts lives in a different directory tree (config, src, pages, strings) Documentum s components don t follow a common organizational structure or use a naming convention Slide 23 of 53

25 Naming conventions Use a naming convention Component and action naming convention *_component.xml *_action.xml *_container.xml *_coordinator.xml Keep config file names consistent with the component/action IDs they contain (newdocument_component.xml) Name JSPs the same as the name of the class but with a lowercase first letter (newdocumentcomponent.jsp) Name NLS properties files the same as the class name with Nls appended (NewDocumentComponentNls.properties) Slide 24 of 53

26 Use a unified source tree Unified source tree with XML, JSP, Java, and properties files in same directory Deploy to appropriate directories using build script Enforces consistency of structure in config and JSP directories based on the package structure so finding configuration files and JSP pages is easy Slide 25 of 53

27 Example of component directory structure Slide 26 of 53

28 Example ant snippet for deploying Slide 27 of 53

29 Developer WDK server packs It is possible to create a self-contained application server environment that doesn t require an installation to be run. Simply unzip, change one path, and run. Includes Jakarta Tomcat JDK DFC WDK application (Webtop, Web Publisher, DA, etc) Great for developers who need to run multiple versions of the software for upgrades, migrations, or different customers Simple installation Slide 28 of 53

30 How to create a WDK server pack Start with a clean machine with no Documentum software installed Install the JDK (1.4.1_07 for example) Install Tomcat ( for example) Install the WDK application Copy the JDK directory (C:\j2sdk1.4.1_07) Copy the Tomcat directory (C:\jakarta-tomcat ) Next, we ll poach files from the WDK install Slide 29 of 53

31 How to create a WDK server pack (continued) Copy the files from the Documentum shared directory (C:\Program Files\Documentum\Shared) Copy the Documentum config directory (C:\Documentum\config) Put all of these copies in a directory and update the catalina.bat file Add the relative paths to the jars to the classpath Add the config directory to the classpath Add the copied Documentum shared directory to the path Update the dfc.properties file with the new path Slide 30 of 53

32 Where are we? Introductions About Blue Fish Improving the development cycle Project organization/deployment Basic WDK Tips Gotchas Questions Slide 31 of 53

33 Customizing components Documentum provides a wide assortment of preexisting components which interact with the repository Most WDK development will involve customizations to an existing WDK application (Webtop, Web Publisher, etc) Inevitably, you will get the request to change the behavior of an existing Documentum component Slide 32 of 53

34 What component am I customizing? The first step is to determine which component you need to customize View source If view source isn t working in IE, delete your Temporary Internet Files (Microsoft Knowledge Base Article #306907) Find component id Search for the component id: <form name= If it s a container, the contained component can be found by searching for: <!-- INCLUDED COMPONENT Slide 33 of 53

35 What component am I customizing example Slide 34 of 53

36 Determine container component Find component/container search for <form name= NewDocContainer component example Slide 35 of 53

37 Determine included component Find included component search for <! INCLUDED COMPONENT newdocument component example Slide 36 of 53

38 Find the newdocument component Search *.xml files for id= newdocument Slide 37 of 53

39 Know the WDK application hierarchy Know the standard WDK application slice hierarchies Webtop custom webtop webcomponent wdk Web Publisher custom wp dam webtop webcomponent wdk Slide 38 of 53

40 Watch what s going on Developers often overlook or fail to effectively utilize the built-in logging and tracing facilities Lots of existing Documentum logging You should consider logging as you are writing your code as it is useful for debugging and remote troubleshooting later Learn how to use log4j as all of the Documentum logging and tracing is built on top of it Slide 39 of 53

41 Basic log4j Typically configured via hierarchical dotted properties file (log4j.properties) Three main concepts Concept Logger Appender Layouts Purpose A level in the hierarchical Logger namespace used to control which log messages are displayed. Each Logger may log messages of one of the priorities: FATAL, ERROR, WARN, INFO, or DEBUG An output destination. May be the console, a file, syslog, etc. The appender controls the characteristics of the output destination such as file name, file size, remote port, etc. Control how each log message is displayed. Configurable by appender Slide 40 of 53

42 Example log4j.properties file Slide 41 of 53

43 Tracing Useful for debugging lower-level portions of the application (DFC and dmcl) Can configure log4j to intersperse DFC/dmcl tracing within application code logs Read the tracing article at dm_developer Slide 42 of 53

44 Where are we? Introductions About Blue Fish Improving the development cycle Project organization/deployment Customizing components Watch what s going on Gotchas Questions Slide 43 of 53

45 Gotchas There is nothing more frustrating to running into something that stops your progress The six gotchas described below are ones that Blue Fish employees and contractors have run into numerous times Slide 44 of 53

46 #1 - BOF classloader issues Version 5.2 of the business objects framework introducted a custom classloader to implement dynamic inheritance (IDfDynamicInheritance) Tomcat configured by DCTM installers to include dfc.jar in the root classpath so the BOF classloader extends the System classloader BOF classes can t exist in a WDK application Slide 45 of 53 Catalina Bootstrap System Common Shared WDK App BOF Class com.documentum.fc.util.bytecode.util InheritanceManagingClassLoader BOF Class

47 #2 - Data dictionary caching issues DFC creates a dmcl directory in the current working directory which caches frequently used data Type caches Object caches Query caches This information isn t always refreshed appropriately after a Data Dictionary publish Delete the dmcl directory (located in the current working directory %CATALINA_HOME%/bin/dmcl) Deleting the dmcl directory also applies to the method server Make this part of your deployment Slide 46 of 53

48 #3 - Create a config directory and an app.xml It s a good idea to create an WDK application slice for your customizations You always have to have at least a minimal app.xml file to insert your slice into the WDK application You must also have a config directory even if you don t have any customizations yet. It can be an empty directory Slide 47 of 53

49 Error without a config directory Could not find java parameter: <context>.war Slide 48 of 53

50 #4 - Make sure you define your parameters A common problem when developing components is to forget to define the parameters that the component expects in the configuration file This often happens if augmenting the component class at a later date. You add the code to the component but the parameter never appears to arrive at your component The WDK framework filters out parameters that are not part of the component definition Slide 49 of 53

51 #5 - Don t throw RuntimeExceptions from actions In components, especially in component lifecycle methods (i.e. oninit) and event handlers, it is common to catch checked exceptions and throw a WrapperRuntimeException The framework handles this for components but eats the exceptions for actions Log your Exception Use the ErrorMessageService to alert the user to a problem with invoking the action Slide 50 of 53

52 #6 - Roles in Webtop Most WDK applications have a need for roles WDK applications use the DocbaseRoleModel to leverage the new role groups in component scoping/filtering If a user isn t in a role, the DocbaseRoleModel falls back to the Client Capability model Make sure you define the standard roles if you are extending Webtop Administrator Consumer (contains Contributor) Contributor (contains Coordinator) Coordinator (contains Administrator) Slide 51 of 53

53 Where are we? Introductions About Blue Fish Improving the development cycle Project organization/deployment Basic WDK Tips Gotchas Questions Slide 52 of 53

54 Questions? A.J. Whitney Documentum Developer Conference 2004