MWLUG  2014

Java:  Finding  Bugs,  Fixing  Bugs        in  IBM  Domino  Designer  and  XPages

Julian  Robichaux      Senior  Software  Engineer,  panagenda  Paul  T.  Calhoun      Senior  Software  Engineer,  panagenda

Your  Speakers

• Julian  Robichaux  - Developer  at  panagenda,  an  Austrian  based  IT  management  software  provider  

- Purveyor  of  nsftools.com  

- Writer  of  open-­‐source  (and  commercial)  software  

- Speaker  at  Lotusphere  since  2006,  many  LUG  and  View  conferences  in  various  countries  

- Doing  almost  exclusively  Java  and  Eclipse  development  (often  Notes  related)  for  the  past  few  years  

- Not  as  pretty  as  Paul  Calhoun,  but  still  easy  on  the  eyes

Your  Speakers

• Paul  T.  Calhoun  - I  have  been  working  with  Lotus/IBM  technologies  for  the  past  25  years.    

- I  have  been  certified  in  both  Administration  and  Development  on  every  major  release  of  Notes/Domino  since  release  3.    

- My  focus  has  always  been  on  training  and  enablement  of  Administrators  and  Developers,  but  I  also  provide  mentoring  and  consulting  services.    

- Most  recently  I  have  been  focused  on  XPages  consulting,  training  and  enablement.    

- When  not  working,  my  passion  is  spending  all  my  spare  time  with  my  awesomely  wonderful  grand-­‐kids.  (WARNING:    I  have  pictures  !)

Agenda

• Debugging  - Java  Agents  

- XPages  

• Logging  • Using  FindBugs  • Using  JConsole  and  Dump  Analysis  

• Q  &  A

Debugging  Java  Agents

• There  are  several  steps  to  enable  a  Java  debugger  to  debug  a  Java  agent  running  on  the  Notes  client:  - Enable  Java  debugging  on  the  Notes  client.  

- Enable  debugging  in  the  agent  (compile  code  with  debug  info).  

- Add  thread  sleep  commands  to  the  Java  agent.  

- Set  breakpoints  in  the  Java  code.  

- Create  a  Debug  Configuration  in  the  Java  Perspective  in  Domino  Designer  to  connect  to  the  Notes  client.  

- Add  the  agent  source  to  the  debug  configuration.  

- Run  the  debugger  in  Domino  Designer  client.  

- Start  the  Notes  agent  to  debug.  

- Debug  the  code  as  needed.  

• Detach  the  debugger  from  Notes.

Enable  Debugger

• Follow  these  steps  to  enable  remote  Java  debugging  on  the  Notes  client:  - Choose    Tools  |  Java  Debugging  Preferences  from  the  menu.  

- In  the  Java  Debugging  Preferences  dialog,  choose  the  appropriate  types  of  agents  to  debug  and  set  the  port  values.      

- Port  values  must  be  unique  when  enabling  debugging  for  more  than  one  type  of  agent.      

- Click  [OK]  to  save  the  settings  and  close  the  dialog.

Enable  Debugger

• Variables  in  the  NOTES.INI  file  are  added  to  reflect  the  port  settings  and  agent  type  selections  - JavaDebugClientForeground=1  

- JavaDebugClientForegroundPort=8701  

- JavaDebugClientScheduled=1  

- JavaDebugClientScheduledPort=8702  

- JavaDebugClientWebPreview=1  

- JavaDebugClientWebPreviewPort=8703  

!• Notes  must  be  restarted  for  the  NOTES.INI  changes  to  take  effect.    Click  [OK]  when  prompted  to  restart  Notes.  

• Exit  and  restart  Notes.

Enable  Agent  for  Debugging

• Follow  these  steps  to  enable  debugging  for  a  Java  agent:  - Open  the  Java  agent's  Properties.  

- From  the  Basics  tab  of  the  Properties  view  • Enable  the  'Compile  Java  code  with  debugging  information'  option.      

• This  will  add  line  numbers  and  information  about  variables  to  the  compiled  code  to  allow  the  agent  to  be  debugged.

Enable  Breakpoints

• Follow  these  steps  to  add  breakpoints  to  an  agent:    - Open  the  agent  in  Designer.      

- Breakpoints  can  be  added  by  either:    • Right-­‐clicking  in  the  left  margin  of  the  code  editor  and  choosing    

• Toggle  Breakpoint  

• Double-­‐clicking  in  the  margin  next  to  the  code  to  add/remove  the  breakpoint.  

- The  breakpoints  are  indicated  by  a  blue  dots  in  the  bar  beside  the  editor  margin.

Create  Debug  Configuration

• This  only  has  to  be  done  once  • In  Designer:  

- Click  the  down  arrow  next  to  the  blue  “Debug”  icon  

- Choose  “Manage  Debug  Configurations”

Create  Debug  Configuration

• In  the  Debug  Configurations  Dialog  - Right  Click  on  “Remote  Java  Application”  

- Choose  “New”

Set  Debug  Configuration

• Provide  a  Name  

• Change  Port  to  Port  set  in  Notes.ini  - Default  is  8701  but  can  be  any  open  port  

• Click  “Apply”  and  “Close”  to  save  • Click  “Apply”  and  “Debug”  to  start  the  debugger  listening  on  the  defined  port

Switch  to  the  Debug  Perspective

• If  not  already  in  the  Debug  Perspective  a  dialog  will  open  prompting  to  switch  to  that  perspective  - Choose  “Yes”  

• Optionally  choose  “Remember  my  decision”  to  suppress  this  dialog  from  popping  up  every  time

The  Debug  Perspective

Debugging

• The  Code  will  stop  at  the  first  breakpoint  • From  there  you  can…  

- Inspect  (and  change)  variables  

- Step  through  the  code  using  the  icons

Stop  the  Debugger

• After  the  debugging  session  is  complete  the  debugger  is  still  “listening”  on  the  open  port  

• In  the  debug  perspective  make  sure  to  “Disconnect”  from  the  listening  port  to  turn  debugging  off

Debugging  Java  XPages

• If  XPages  make  calls  to  Java  Code  elements  then  that  Java  code  can  be  debugged  using  a  similar  process  to  debugging  agents.  

• In  order  to  debug  Java  code  called  by  an  XPage  add  the  following  lines  to  the  notes.ini    - JavaEnableDebug=1  

- JavaDebugOptions=transport=dt_socket,server=y,suspend=n,address=<port  to  listen  on>  

• GOTCHA  !!  - If  the  previous  ports  are  enabled  for  Java  agent  debugging  then  “connecting”  to  the  port  above  will  never  work  

- Disable  the  Java  Debug  Ports  and  restart  your  Notes,  Designer  client  prior  to  debugging  Java  called  from  XPages  

- Your  firewall  might  block  the  port

Debug  Configuration

• Create  a  new  Debug  Configuration  to  “listen”  on  the  port  that  was  set  in  the  notes.ini  file  

• Preview  the  XPage  to  start  the  local  web  preview  • Start  the  debugger

Execute  XPage  Action

• Set  breakpoints  in  the  Java  code  to  be  debugged  • In  the  XPage  in  the  browser  

- Execute  the  action  that  will  call  the  Java  code  

• If  not  already  in  the  Debug  perspective  you  will  be  prompted  to  switch  to  that  perspective  

• Step  through  your  code  reviewing  the  variable  values  at  each  breakpoint  

• Clear  breakpoints  and  resume  to  end  

• Disconnect  from  Debugger  when  done.

WARNING

DO  NOT  EVER  ENABLE  DEBUGGING  ON  A  

PRODUCTION  SERVER

Demo

Agenda

• Debugging  - Java  Agents  

- XPages  

• Logging  • Using  FindBugs  • Using  JConsole  and  Dump  Analysis  

• Q  &  A

Logging

Logging  Basics

• System.out.println()  is  NOT  logging!

• Java  has  native  logging  classes  - java.util.logging  

- There  are  other  popular  logging  frameworks,  which  we  will  ignore  for  the  sake  of  brevity  

- The  native  Java  classes  work  just  fine

• The  big  picture:  - Each  bit  of  code  can  have  its  own  logger,  or  loggers  can  be  shared  

- Java  manages  all  the  different  loggers  being  used  

- The  logging  level  determines  the  severity  of  the  message  

- Different  handlers  send  messages  to  the  console  or  to  files

Logging  Example

create  logger

log  to  various  levels

easy  Exception  handling

Logging  Levels

• Log  Levels,  in  order  of  highest  to  lowest:  - SEVERE  –  serious  failure,  horrible  stuff  

- WARNING  –  potential  problem  

- INFO  –  informational,  non-­‐technical

- CONFIG  –  system/program  configuration

- FINE  –  simplest  trace  messages  

- FINER  –  medium  trace  messages  

- FINEST  –  detailed  trace  messages

Interpreting  Levels

• What  level  you  use  for  your  messages  is  a  matter  of  personal  preference.  Here’s  a  general  guideline/suggestion:  - Showstopping  issues  go  to  SEVERE    

- Errors  your  admin  (and  nosy  users)  should  see  go  to  WARNING    

- Unobtrusive  “heartbeat”  kinds  of  messages  go  to  INFO    

- Start  and  stop  messages  go  to  CONFIG    

- Debug  info  goes  to  FINE/ER/EST,  with  FINEST  being  very  tedious  and  verbose    • These  are  “trace”  levels  

• Generally  only  enabled  for  troubleshooting  purposes

Log  Handlers

• Typical  log  handlers  write  to  either  the  console  or  a  file

• There  are  default  handlers  for  different  contexts  - Java  agents:  Java  console  (client),  server  console  (server)  

- XPages:  server  console  (server),  files  (client  and  server)  

- Plugins:  OSGi  console,  files

• Handlers  also  have  levels  - Console  normally  only  displays  log  messages  for  SEVERE,  WARNING,  and  INFO  

- File  logs  often  display  log  messages  for  all  levels

Logging  Example

where  did  this  one  go?

Log  Levels  and  Output

• Loggers  often  have  a  default  level  of  INFO

• This  means  that  by  default,  any  messages  with  a  level  lower  than  INFO  will  not  be  logged  anywhere  - So  messages  at  level  CONFIG  and  FINE/ER/EST  will  never  be  sent  to  a  Handler  because  the  Logger  discards  them

• Messages  get  filtered  by  the  Logger  before  they  are  passed  to  the  Handler    - Even  a  Handler  at  Level.FINEST  will  not  get  any  FINE/ER/EST  messages  if  the  Logger  is  set  to  Level.INFO

Adjusting  Log  Levels

• Adjusting  log  levels  programmatically  - setLevel()  for  Logger  and  Handler  

- This  will  cause  a  SecurityException!  

- You  can  get  around  this  by  editing    jvm/lib/security/java.policy  - permission java.util.logging.LoggingPermission "control"  

• Adjusting  log  levels  with  config  files  - Notes  agents:  {notes}\jvm\lib\logging.properties  

- XPages:  {domino}\data\domino\workspace\.config\rcpinstall.properties

Example  Log  Level  Adjustment

Don’t  forget  the  .level!

Logging  Quirks  in  Notes

• Prior  to  8.5.3  FP2,  Java  logging  in  Notes  worked  just  fine  - Although  logging  in  local  agents  didn’t  log  anywhere  by  default

• In  9.0.0  and  8.5.3  FP2,  FP3,  and  FP4  Java  logging  gave  errors  - java.security.AccessControlException  

- Add  LoggingPermission  to    jvm/lib/security/java.policy

• In  9.0.1  and  8.5.3  FP5,  Java  logging  worked  again  - NEW:  Local  Java  agents  log  to  the  Java  Agent  Console  by  default  

- NEW:  if  you  still  need  the  LoggingPermission  so  you  can  set  custom  Handlers  or  Levels,  you  also  need  to  add  a  special  SecurityPermission  • http://www-­‐01.ibm.com/support/docview.wss?uid=swg21669594

XPages  Log  Output

• XPages  logging  trace  log  files  - Server  8.5.1:  none,  server  console  only  

- Server  8.5.2+:  {domino}\data\domino\workspace\logs  • SEVERE  messages  still  show  up  on  the  console  too  

- XPiNC:  {notes}\data\workspace\logs

• Default  logger  level  is  WARNING,  not  INFO

• Prior  to  8.5.3,  non-­‐logged  XPages  exceptions  also  used  to  show  up  in  the  trace  logs.  Now  they  are  in  {notes}\data\IBM_TECHNICAL_SUPPORT\xpages_exc_*.log    - http://www-­‐01.ibm.com/support/docview.wss?uid=swg1LO66802  

Viewing  Trace  Log  Files

• Trying  to  view  the  trace  log  files  as  raw  XML  is…  painful

• A  better  way  is  to  right-­‐click  them  in  the  “logs”  folder  and  open  them  in  a  browser  - There  is  an  XSLT  file  that  will  format  them  nicely  for  you

• HOWEVER,  if  the  client  or  server  is  still  running,  the  XSLT  file  won’t  work  because  the  closing  XML  tag  is  missing  - Make  a  copy,  open  in  a  text  editor,  and  add  a  closing    </CommonBaseEvents>    tag  to  the  end.  Then  open  in  a  browser.  

- Make  sure  you  open  the  copy  from  within  the  “logs”  folder;  otherwise  the  XSLT  file  will  not  be  found  

- Sometimes  log  messages  don’t  show  up  immediately  in  the  log  files!  Everything  gets  flushed  when  you  shut  down  the  server.

XPages  Logging  Example

XPages  Logging  Example

XPages  Logging  Example

Logging  Best  Practices

• Use  the  same  logger  for  your  entire  package  (maybe  even  your  entire  library)  

• Most  messages  should  be  logged  to  FINE/ER/EST;  don’t  clutter  up  the  console  with  INFO  messages  

• Log  actions,  but  not  every  step  of  a  method  or  every  single  get/set  –  logging  is  NOT  a  replacement  for  a  debugger  

• DO  NOT  EVER  log  sensitive  data  - Personal  user  information,  passwords,  system  “secrets”  

- “No  one  will  ever  look  at  those  anyway”  is  bad  security

Agenda

• Debugging  - Java  Agents  

- XPages  

• Logging  • Using  FindBugs  • Using  JConsole  and  Dump  Analysis  

• Q  &  A

FindBugs

• FindBugs  is  a  program  that  uses  static  analysis  to  look  for  bugs  in  Java  code.  - Current  version  is  3.x  

• Source  and  Documentation  at  - http://findbugs.cs.umd.edu/eclipse  

• Latest  version  of  FindBugs  CANNOT  be  installed  into  DDE  natively    - Either  install  in  a  stand  alone  version  of  Eclipse  

- Use  FindBugs  for  Domino  Designer  from  OpenNTF  

- FYI,  This  is  a  version  2.x  implementation  of  FindBugs  • http://www.openntf.org/main.nsf/project.xsp?r=project/FindBugs

%20for%20DominoDesigner  

FindBugs

• Available  as  an  Eclipse  plug-­‐in,  install  instructions  at  - http://findbugs.cs.umd.edu/eclipse  

• Agents  contained  in  an  NSF  are  not  “readable”  during  the  FindBugs  analysis.  - The  agent  code  will  need  to  be  exported  and  imported  into  Eclipse  for  analysis.

Change  FindBugs  Properties

• Change  the  FindBugs  Properties  to  show  all  bugs

Running  FindBugs

• In  Domino  Designer  open  the  Package  Explorer  view  - If  this  view  is  not  in  the  current  perspective,  either  

• Switch  to  the  XPages  perspective  

• Add  it  to  the  current  working  perspective  

• Right  click  over  the  code  folder  to  be  analyzed  and  choose  “Run  FindBugs”

FindBugs  Perspective

• After  analyzing  code,  switch  to  the  FindBugs  perspective    • Or  add  the  Bug  Explorer  view  to  the  current  perspective  • Remediate  the  found  bugs

Demo

Agenda

• Debugging  - Java  Agents  

- XPages  

• Logging  • Using  FindBugs  • Using  JConsole  and  Dump  Analysis  

• Q  &  A

My  Notes  Client  is  Slow!

• Troubleshooting  slow  performance  is  tricky  - How  do  you  define  “slow”?  

- How  do  you  know  it’s  your  code  and  not  something  else?  

- Task  Manager  only  tells  you  about  high-­‐level  processes

• Much  easier  to  troubleshoot  on  a  client,  rather  than  a  server  - Not  disruptive  to  restart  

- Easy  to  change  parameters  

- Crash  at  will!

• Whenever  possible,  port  your  Java  code  to  a  local  Notes  agent  or  a  local  XPage  for  troubleshooting

A  Tale  of  Two  VMs

• The  Notes  client  actually  has  two  Java  VMs  for  running  code  - Java  agents  

- The  rest  of  the  Notes  client  (including  local  XPages)

• The  VM  for  Java  agents  is  adjusted  with:  - Notes.ini  settings  

-  {notes}\jvm\lib    properties  files

• The  VM  for  everything  else  (on  the  client)  is  adjusted  with:  - {notes}\framework\rcp\deploy\jvm.properties

- {data}\workspace\.config\rcpinstall.properties

JConsole

• JConsole  is  a  tool  for  monitoring  performance  and  resource  usage  in  a  running  JVM  - http://docs.oracle.com/javase/6/docs/technotes/guides/management/jconsole.html  

• I  wrote  an  article  on  setting  this  up  for  local  XPages  and  plugins  (non-­‐Java-­‐agents)  here:  - http://www.socialbizug.org/blogs/2ec5d0ed-­‐d04e-­‐4b18-­‐9610-­‐9819fcebca79/entry/using_jconsole_to_monitor_your_ibm_notes_client  

• Quick  demo…  

JConsole  Screenshot

JConsole  for  Local  Java  Agents

• To  use  JConsole  to  monitor  local  Java  agents,  there’s  a  trick  - Add  JavaUserOptionsFile  to  your  Notes.ini  file:  

• JavaUserOptionsFile=c:\IBM\Notes\java.options.txt  

- In  your  Java  options  file  add  these  lines:  • -­‐Dcom.sun.management.jmxremote.port=9876

-­‐Dcom.sun.management.jmxremote.ssl=false-­‐Dcom.sun.management.jmxremote.authenticate=false

• Connect  JConsole  to  the  jmxremote.port  you  defined  - This  port  won’t  be  active  until  AFTER  you  run  a  Java  agent  

- Make  sure  nothing  else  is  using  that  port  

- Make  sure  the  firewall  allows  that  port  to  be  used

JavaUserOptionsFile

Analyzing  Dump  Files

• If  your  Notes  client  (or  Domino  server)  crashes  due  to  a  Java  problem,  it  will  usually  generate  a  core  dump  file  - default  location  is  workspace\logs  

- Just  a  text  file  

- Shows  what  threads  were  running,  system  info,  etc.

• IBM  Thread  and  Memory  Dump  Analyzer  does  a  good  job  of  parsing  the  core  dump  file  for  you  - https://www.ibm.com/developerworks/community/groups/service/html/communityview?communityUuid=2245aa39-­‐fa5c-­‐4475-­‐b891-­‐14c205f7333c  

- run  like  this:      java -Xmx500m -jar jca455.jar

IBM  Memory  Dump  Analyzer

Heap  Dumps

• Heap  Dumps  are  a  snapshot  of  the  JVM  threads  and  processes  at  a  specific  point  in  time,  while  it’s  running  - Like  a  slice  of  what  you  see  in  JConsole

• Used  for:  - Tracking  down  memory  leaks  

- Finding  high-­‐memory-­‐use  objects  (and  arrays)  

- Finding  objects  that  are  unexpectedly  still  in  memory

• IBM  Heap  Analyzer  is  a  nice  tool  for  viewing  the  information  - https://www.ibm.com/developerworks/community/alphaworks/tech/

heapanalyzer    

- http://www-­‐01.ibm.com/support/docview.wss?uid=swg27006624&aid=1

How  to  Generate  a  Heap  Dump

• Generating  a  Heap  Dump  file  (no  crash  required!)  - Domino  XPages  

• tell http xsp heap dump

• XPages  Toolbox  (  http://www.openntf.org/p/XPages%20Toolbox  )

- Notes  Client  (from  a  command  prompt)  • notes\framework\rcp\rcplauncher.exe  -­‐com.ibm.rcp.core.logger#dump  heap  -­‐dumps  heapdump  

• writes  to  {data}\workspace\logs\heapdump.###.phd  by  default  

• You  can  also  do  a  core  (thread)  dump  with:  • notes\framework\rcp\rcplauncher.exe  -­‐com.ibm.rcp.core.logger#dump  threads  -­‐dumps  javacore

- Java  Agent  • com.ibm.jvm.Dump.HeapDump();

• writes  to  {notes}\framework\heapdump.###.phd  

IBM  Heap  Analyzer  Screenshot

IBM  Heap  Analyzer  Screenshot

IBM  Heap  Analyzer  Screenshot

2318  Notes  Documents  2318  Notes  Items                1  Notes  View                1  Notes  Database                1  Notes  Session                1  ???  ———————————  4640  NotesWeakReferences

Agenda

• Debugging  - Java  Agents  

- XPages  

• Logging  • Using  FindBugs  • Using  JConsole  and  Dump  Analysis  

• Q  &  A

Q  &  A

Questions?  Anyone?

MWLUG  2014

THANK  YOUJulian  Robichaux  panagenda  jrobichaux@panagenda.com

Paul  Calhoun  panagenda  paul.calhoun@panagenda.com