OpenOffice Debugging Java components


Contents

General
Debugging from NetBeans or Forte
Attach to a running debugger
Using the classic VM
Registration hints

General

To debug java components one can use the Java Platform Debugger Architecture (JPDA) which is part of the jdk 1.3. Please read also the respective guide and the jdb documentation which are part of the jdk documentation.

Both, the Java Virtual Machine (VM) and the debugger, such as jdb, need the PATH environment variable set to the jdk/bin directory. JPDA requires that the VM is started with some dedicated options in order to enable a connection with a debugger. When using the hotspot VM, which is the default with OO, there are two options that have to be put into the java.ini (javarc on Solaris) file. Those options are:

      -Xdebug
      -Xrunjdwp:transport=dt_socket,server=y,address=8000
      
The entries have to be put into the java section. For example:
      [Java]
      Home=d:\development\jdk1.3.1
      VMType=jdk
      Version=1.3.1
      RuntimeLib=d:\development\jdk1.3.1\jre\bin\hotspot\jvm.dll
      SystemClasspath=d:\development\jdk1.3.1\jre\lib\rt.jar;d:\development\jdk1.3.1\jre\lib\i18n.jar; \
          d:\development\jdk1.3.1\lib\tools.jar;d:\development\jdk1.3.1\lib\dt.jar; \
          d:\development\jdk1.3.1\lib;d:\641m3\program\classes\classes.jar;\
          d:\641m3\program\classes\sandbox.jar;d:\641m3\program\classes\ridl.jar;d:\641m3\program\classes\unoil.jar;\
          d:\641m3\program\classes\jurt.jar;d:\641m3\program\classes\juh.jar;d:\641m3\program\classes\swingall.jar;\
          d:\641m3\program\classes\java_uno.jar;d:\641m3\program\classes\xmlhelp.jar;\
          d:\641m3\program\classes\xmlsearch.jar;d:\641m3\program\classes\db.jar;d:\641m3\program\classes\xt.jar;\
          d:\641m3\program\classes\jaxp.jar;d:\641m3\program\classes\parser.jar;
      Java=1
      JavaScript=1
      Applets=1
      -Xdebug
      -Xrunjdwp:transport=dt_socket,server=y,address=8000
      
-Xdebug tells the VM that debugging is to be enabled. The second option contains several information about the details of the connection between debuggee and debugger. In short, the string effects that the VM listens to port 8000 for a debugger and stops until a debugger has connected. Data between VM and debugger are transfered through sockets. The port (address= ....) can be freely choosen, but should not conflict with other programs. Use a program like netstat to figure out the already occupied ports.

If you do not want the the VM and hence the OO to block until the debugger connects to the VM you can add "suspend=n". For example:

      -Xrunjdwp:transport=dt_socket,server=y,address=8000,suspend=n
      
suspend=y is the default and need not to be specified in the option string.

To start the debugger enter this command:

      jdb -connect com.sun.jdi.SocketAttach:hostname=localhost,port=8000
      
If the VM runs on a different machine then one has to use the respective hostname as argument. For example
      jdb -connect com.sun.jdi.SocketAttach:hamburg-11070,port=8000
      
In this example hamburg-11070 is the computer that runs the VM.

Note that the debugger does not require to have the the CLASSPATH environment variable set. It need not to know all the classes and jar files which the debugged program uses.

Debugging from NetBeans or Forte

If you use NetBeans or Forte, you can easily attach to the VM. Choose menu Debug->Attach to open the connect dialog. Then select the JPDA debugger and enter the computer name and port. Before attaching one should select the appropriate source file into the editor and set the breakpoints at will. This requires that the directory containing the source file is mounted.


Attach to a running debugger

JPDA allows also the VM to attach to the debugger. In the examples above the debugger connects to the VM instead. When VM attaches to the debugger then the entry in the java.ini file has to be changed to read

      -Xdebug
      -Xrunjdwp:transport=dt_socket,address:localhost:8000
      
To start the debugger type:
      jdb -connect com.sun.jdi.SocketListen:port=8000
      
After attaching to the debugger the VM will block until you type resume at the debugger promt, or have the thread continue within an IDE.

Make sure that the debugger is running when the VM instantiated, otherwise the VM, and hence OO, will crash.

NetBeans and Forte currently do not support this kind of debugging.


Using the classic VM

Using the classic VM with JPDA requires to put two additional entries in the java.ini file. For example

      -Xdebug
      -Xrunjdwp:transport=dt_socket,server=y,address=8000
      -Xnoagent
      java.compiler=NONE
      
The first to entries are the same as used with the hotspot VM. Note, you must not write
      -Djava.compiler=NONE
      
because the VM service will prepend "-D" to all entries which do not have a special meaning. That is, to add addional properties, you can write:
      myProp1=some_value
      myProp2=some_value
      


Registration hints

When you register a Java service then the regcomp program instantiates several other services to carry out registration. Those services are not only bootstrap services (i.e. regcomp knows how to find an instantiate those services),and hence regcomp needs to be told about those service. This is done by applying a command line argument that specifies a registry which contains the appropriate information. That argument starts with -br. The easiest way is to use the applicat.rdb of an installed office. Change into the program directory and type

      regcomp -register -br applicat.rdb -r applcat.rdb
              -c file:///d:/office/program/JavaComponent.jar
              -l com.sun.star.loader.Java2
      

When the VM service is instantiated it will use configuration settings to configure the VM.
Therefore make sure that Java is enabled. This can be done in the options dialog of OO. Choose menu Tools->Options so that the dialog appears. Then expand the StarOffice node and select Security. Finally find the Enable checkbox in the Java section on the right side, select it, and click the OK button.

Make sure that the manifest file contains the entry
RegistrationClassName: NameOfClass
And that that class is the one which implemens the __writeRegistryServiceInfo method.

If the component depends on other jar files or classes then you can either edit the java.ini file and add them to the SystemClasspath entry or you use the option dialog to add them to the user classpath. The user classpath can be found in the security pane. The jar file that contains the component does not need to be put in the java.ini or user classpath.

If you have already put debug options (-Xdebug, -Xrunjdwp) in the java.ini file then disable them by putting semicolons at the beginning of the respective lines.

Author: Jürgen Schmidt ( 2001-11-07 12:54 PM )
Copyright 2001 Sun Microsystems, Inc., 901 San Antonio Road, Palo Alto, CA 94303 USA.