Debugging Java in Agents, Script Libraries, and XPages

Transcription

1 Debugging Java in Agents, Script Libraries, and XPages Julian Robichaux, panagenda IBM Notes den EierlegendenWollMilchSau für alle und Immer

2 Who Am I? Julian Robichaux Senior Application Developer, panagenda Notes developer since 1996 nsftools.com since 2002 Conference speaker since 2006 IBM Champion since (since 2007)

3 Why Are We Here? Debugging Java in Notes/Domino! It s easier than you think I do this all the time Eclipse is magical Java agents and XPages Java Tips at the end about creating/reading Java core dumps, finding bugs before the code runs, and more! N.B. this is from a presentation I gave with Mark Myers (LDC). HI MARK!

4 What Will We Be Using? IBM Domino Server FP4 IBM Domino Designer (DDE) FP4 Java 1.6 (as included with Domino and DDE) XPages and Java agents Eclipse

5 The Ninja Classes The Java classes we use for demonstration are based [very loosely] on Ninja prowess and skill public int attack (Ninja otherninja, IMove move) throws NinjaException { } int damageinflicted = attemptmove(move); otherninja.suffer(move); return damageinflicted;

6 The Ninja Classes

7 The Java Debug Console

8 What Is Debugging? Kind of a silly question, but one we need to address Many possible answers: Logging Capturing errors Reproducing problems Stepping through code Looking at crash dumps

9 Classic Notes Java Debugging System.out.println()!!

10 The Lowly Java Console Captures System.out and System.err messages from Java agent code run on the Notes client Tools Show Java Debug Console Problem with DDE: sometimes the debug console won t open Solution: completely shut down the Notes client and DDE, restart Notes, launch the debug console before you open DDE

11 Debug Console Tricks Type v for Java Version info

12 Debug Console Tricks (cont.) m for memory available, f for finalization, g for garbage collection

13 Debug Console Tricks (cont.) p for system properties

14 Debug Console Tricks (cont.) control-alt-e for the Euro symbol Just some crazy thing my Windows XP machine does (might not work for you)

15 That s Great, But It s not much more than seeing the output of print statements Only from Agents, not XPages Since Notes 7, we have the ability to attach a real Java debugger to the client Including, but not limited to, Eclipse Set breakpoints, step through code, inspect variables, etc.

16 Eclipse or DDE? DDE comes with the Eclipse debugger, so you have a choice Sometimes it s more convenient to use standalone Eclipse, sometimes DDE I will show you both, starting with Eclipse

17 Debugging Java agents and script libraries

18 Setting up the Notes Client for Debugging Tools Java Debugging Preferences

19 Setting up the Notes Client for Debugging (cont.) Select the options and ports you want Client Agents are triggered agents Locally Scheduled Agents are just what they sound like Http Preview is Java code run from a Web page, served by the local nhttp process

20 Setting up the Notes Client for Debugging (cont.) Client restart is required when you make changes

21 Check Your Firewall Settings Nlnotes.exe must be allowed to use those ports in your workstation firewall settings

22 Check Your Firewall Settings (cont.)

23 Create a Java Agent Open a database in DDE, and go to the Code Agents section Click the New Agent button

24 Create a Java Agent (cont.) Give the agent a name, and make sure the Type is set to Java

25 Create a Java Agent (cont.) Import the NinjaClasses script library into the agent

26 Create a Java Agent (cont.) Double-click the JavaAgent.java entry in the Agent Contents list

27 Create a Java Agent (cont.) Add some code to the agent

28 Create a Java Agent (cont.) Close the JavaAgent.java tab, and choose Yes when you are prompted to save your changes

29 Create a Java Agent (cont.) Make sure these Agent Properties are set: Target = None (standard agent setting) Compile Java code with debugging information checked See screenshot on next slide The Compile with debugging information is very important, and is NOT checked by default Allows the debugger to know what line it s on after the source code has been compiled to bytecode Adds line numbers and method info to stack trace No performance loss

30 Create a Java Agent (cont.)

31 Create a Java Agent (cont.) Click the Export button to export the agent code to a local file

32 Create a Java Agent (cont.) Save and close the Java agent It can now be run from the Actions menu of the database If you want, you can open the debug console and see the System.out message get printed when the agent runs! Amazing! Now, let s set up the debugger

33 Install Eclipse Make sure Java (standalone) is installed on your workstation Java 1.5 or higher (I use 1.6) JRE will work, but you may as well use a full JDK Download a version of Eclipse 3.4 (Ganymede) or higher This is simply a ZIP file that must be unzippped Do NOT use native Windows unzip. 7-Zip is a good choice. It is better to install Eclipse in a short folder name (like c:\eclipse)

34 A Word About Versions I usually use Java 1.6 and Eclipse 3.4, because that matches the versions of Java and Eclipse in the Notes 9 client when I write Eclipse plugins I don t have compatibility issues All these things should work with newer versions of Java and Eclipse too! Eclipse 4 is much sexier than Eclipse 3

35 Launch Eclipse Double-click eclipse.exe

36 Launch Eclipse (cont.) Create a new Workspace for our debugger project

37 Launch Eclipse (cont.)

38 Create a New Java Project File New Java Project

39 Create a New Java Project (cont.) Name the project, click Finish

40 Create a New Java Project (cont.) Right-click the new project in Package Explorer and choose the menu option Import

41 Create a New Java Project (cont.) Use an import source of: General File System

42 Create a New Java Project (cont.) Select the directory you exported the Java agent to earlier, and all the files in that directory Import into folder: ProjectName/src Click Finish

43 Create a New Java Project (cont.) The project will now look like this:

44 Add Missing JAR Files to Java Build Path Not strictly necessary, but gets rid of all those red X s Choose the menu item Project Properties

45 Add Missing JAR Files to Java Build Path (cont.) Select Java Build Path from the left-hand list Go to the Libraries tab Click the Add External JARs button Select Notes.jar from your Notes\jvm\lib\ext directory Select Ninja.jar from wherever you have that stored NOTE: or you can import the Ninja class source code directly into your project Click OK to save the changes

46 Add Missing JAR Files to Java Build Path (cont.)

47 Show Line Numbers Eclipse doesn t usually show line numbers by default Right-click the gutter just to the left of the code (where line numbers should be) and choose the menu option Show line numbers

48 Open the Debug Perspective Window Open Perspective Debug

49 Open the Debug Perspective (cont.)

50 Can We Start Debugging Now? Almost there

51 Set a Breakpoint in the Code Double-click a line number to toggle the breakpoint at that line The breakpoint will be shown as a small blue ball in the gutter area to the left of the line numbers

52 Create a Debug Configuration Click the down-arrow next to the small bug icon in the task bar Then choose Debug Configurations from the drop-down menu

53 Create a Debug Configuration (cont.) Right-click Remote Java Application in the Debug Configuration list, and choose New

54 Create a Debug Configuration (cont.) Use the following settings: Name: JavaAgent Connection Type: Standard (Socket Attach) Host: localhost Port: 8701 Click Apply to save your changes

55 Create a Debug Configuration (cont.)

56 Start Debugging Make sure the Notes client is running Click the Debug button at the bottom of the Debug Configuration dialog If the debugger attaches successfully, you will see something like this:

57 Errors Starting the Debugger? Errors in Workspace You can ignore this if you get it. It just means that there are unresolved dependencies or something in the code you imported. Not important for the debugging we re doing.

58 Errors Starting the Debugger? (cont.) Failed to connect to remote VM Make sure the Notes client is running, and that you set the debugging properties properly, and that you restarted the client after you set the properties Has the Notes JVM started yet? Launch the Java Debug Console to be sure. Check your firewall Check your port numbers Use TCPView from Sysinternals or Windows 8 Resource Monitor to determine which ports are currently in use

59 Run the Agent! Open the database in the Notes client Choose the menu option Actions NinjaDebugTest When the code hits the breakpoint, the debugger should suspend the agent thread

60 Debugging the Live Agent

61 Basic Debugging Actions Resume Use Step Filters Disconnect Step Into, Step Over, Step Return

62 Step Filters List of classes or packages to ignore when you do a Step Into So you don t step into classes you have no source code for Good packages to add: com.ibm.* COM.ibm.* (if available, case-sensitive) lotus.domino.* org.apache.*

63 Step Filters (cont.)

64 Inspecting Variables Variables and objects for the current code context can be found in the Variables view of the Debug perspective By default, this will be in the top right of the perspective Double-click the tab to maximize it temporarily

65 Inspecting Variables (cont.) If you select a variable or object in the list, its string value will be displayed in the bottom pane of the Variables view

66 Inspecting Variables (cont.) If you click on a scalar value in the Variables list, you can modify that value for the current run of the code

67 Evaluating Code The Display console allows you to execute small bits of code to evaluate them against the current context and see the result To open the Display view, choose the menu option Window Show View Display

68 Evaluating Code (cont.) In the Display console, you can type arbitrary expressions to be evaluated Type the expression in the console view Select the entire expression (as though you were about to copy to the clipboard) Click the Display result of evaluating selected text button in the Display console toolbar

69 Evaluating Code (cont.) If the expression you run changes a value in an object, that value will remain changed when the code continues

70 When You re Done Don t forget to disconnect!

71 Other Fun Tricks The Eclipse debugger has a lot of other interesting (and useful) bits of functionality Conditional breakpoints Exception breakpoints Detail formatters Watch values Copy stack And more Many good resources on the Internet

72 Issues and Problems You MUST export source code from Notes, and keep it in sync with Eclipse But wait, you can do this within DDE too! No export needed. We will see this next Script libraries must also be exported in order to debug attached code Once the debugger is running, it will hit the line number breakpoint for ALL agents that run, not just the one you want to debug Firewalls can get in the way Use Sysinternals TCPView or Windows 8 Resource Monitor to check ports

73 TIME CHECK 16:45?

74 Debugging Java in XPages

75 Debugging Java in XPages Java can be called from SSJS on an XPage If it s your own custom Java class (as source code), it can be debugged NOTE: debugging JavaScript is outside the scope of this session; we re only talking about Java here

76 Notes 8.5 vs 9.0 The steps in this section are for Notes/DDE 9.0 If you are still using DDE 8.5, there are some differences: the Java design element did not exist until the JAR file design element did not exist until 9.0 you can still add Java code and JAR files for XPages in older versions of 8.5, but you have to use the Package Explorer view and modify the Build Path Work_with_Java

77 Import the Ninja JAR File

78 Create an XPage-able Java Class

79 Create an XPage-able Java Class (cont.) Give the new class a Package and a Name:

80 Create an XPage-able Java Class (cont.) The new class file should now be open in DDE for editing

81 Create an XPage-able Java Class (cont.) Add some code to the class and save it

82 Create a New XPage Back in the Applications view in DDE, go to the XPages section of your database and click the New XPage button

83 Create a New XPage (cont.) Give the XPage a name, and click OK

84 Create a New XPage (cont.) Drag a new Label control to the XPage, and give it a Label value of Random Ninja Move:

85 Create a New XPage (cont.) Drag a Computed Field control to the XPage, and give it a JavaScript value as shown below

86 Create a New XPage (cont.) Save the XPage and test it in a browser

87 Setting Up Debugging Add the following lines to your Domino server s Notes.ini This will require at least a restart task http to take effect The address=9700 variable is the port that debuggers will attach to As always, check your firewall rules JavaEnableDebug=1 JavaDebugOptions=transport=dt_socket,server=y,suspend=n,address=9700

88 Setting Up Debugging (cont.) Open your test Java class in DDE again Click the down arrow beside the GREEN bug icon in the toolbar, and choose Debug Configurations

89 Setting Up Debugging (cont.) In the Debug Configurations dialog, right-click the Remote Java Application item and choose New

90 Setting Up Debugging (cont.) Adjust the host and port as needed, and click Apply This is the port from the notes.ini JavaDebugOptions

91 Setting Up Debugging (cont.) Make sure you ve restarted the Domino server or the HTTP task after you added the Notes.ini debug entries Click the Debug button in the Debug Configuration dialog

92 Setting Up Debugging (cont.) Double-click a line number in the Java code to add or remove the breakpoint at that line The breakpoint will be shown as a small blue ball in the gutter area to the left

93 Debug the Code! Refresh the XPage in a browser. When your breakpoint gets triggered, you will see a dialog in DDE asking if you want to switch to the Debug Perspective. Choose Yes.

94 Debug the Code!

95 Standard Eclipse Debugging From there, you can use standard Eclipse debugging as we demonstrated earlier Troubleshooting is the same too: Check the firewall port settings Check active ports in TCPView or similar Etc. Don t forget to disconnect! You can switch from the Debug perspective back to the normal DDE perspective with Window Open Perspective Domino Designer

96 Things to Watch Out For The debug port will only allow one connection at a time The debug port is incredibly insecure ANYONE with access to your server can connect to it There is no good way to specify (to the server) which piece of code you want to debug. If you set a breakpoint at line 10, then ALL Java XPages code will pause at line 10. As a result of these things, do NOT enable debugging on a production server

97 Which One To Use? Eclipse or DDE?

98 Nice Things About DDE Fewer steps involved Code is always in sync (no need to export to Eclipse) You are already using it!

99 Nice Things About Eclipse Newer versions have newer features and fixes for debugging these are usually minor Runs in a separate memory space useful for debugging big agents If you build JAR files in Eclipse for deployment to Notes/Domino, you can debug from the same place you write the JAR file Eclipse is a good tool to have (it can do so many more things)

100 Performance Analysis and Troubleshooting

101 Code Optimization Make your code work first, then worry about speed You always want working code to fall back on Is it fast enough? Leave it alone. Making code shorter doesn t make it faster Clever code is harder to troubleshoot Don t assume you know where the bottleneck is We should forget about small efficiencies, say about 97% of the time: premature optimization is the root of all evil - Donald Knuth

102 Static Code Analyzers FindBugs is a great tool for finding potential problems Bugs grouped by categories and subcategories, like: Security Scary Performance Dodgy Code New cloud option for development teams Rank bugs, assign fixes

103 FindBugs

104 FindBugs

105 Common Bottlenecks Some other guy s server Slow database queries Memory issues Leaks (less common than you think) Too much cached information, especially large objects, strings, XML Loading and unloading resources Non-lazy initialization of objects Slow or broken network connection

106 Simulating Poor Network Connections Network Link Conditioner (OSX) XCode > Open Developer Tool > More Developer Tools

107 Analyzing Java Memory Usage Used for: Tracking down memory leaks Finding high-memory-use objects (and arrays) Finding objects that are unexpectedly still in memory YourKit Java profiling app Eclipse Memory Analysis Tool

108 Analyzing Java Memory Usage IBM Thread and Dump Analyzer (for javacore files) communityview?communityuuid=2245aa39-fa5c b891-14c205f7333c IBM Heap Analyzer (for heapdump files) heapanalyzer

109 Generating Heap Dumps with Notes/Domino Domino XPages tell http xsp heapdump XPages Toolbox ( ) Directly from Java Agents or Classes com.ibm.jvm.dump.heapdump(); writes to notes\framework\heapdump.###.phd when run from an agent writes to the Domino program directory when run from an XPage there will be a message on the server console with the file location

110 Generating Heap Dumps with Notes/Domino Notes Client (Expeditor) this will give you information about Eclipse plugins open a Command Prompt while the Notes client is running change to the notes\framework\rcp\ directory enter one of the following commands: rcplauncher -dcommand_only -com.ibm.rcp.core.logger#dump heap rcplauncher -dcommand_only -com.ibm.rcp.core.logger#dump threads writes to notes\data\workspace\logs by default

111

112 Conclusion

113 Additional Resources Eclipse debugging eclipsetutorial.sourceforge.net/debugger.html blog.codecentric.de/en/2013/04/again-10-tips-on-java-debugging-witheclipse

114 Thank you IBM Notes den EierlegendenWollMilchSau für alle und Immer