jBixbe 1.1 HowTo

This HowTo gives a brief description for the important tasks when using jBixbe. It's not a step by step guide.

How to start jBixbe?

jBixbe comes as jbixbe.jar or jbixbe.exe. Under Windows both files can be started by a double click on it. You can also use a shell (e.g. the command line cmd under Windows or any Linux console under Linux) and type java -jar jbixbe.jar.

How to use the tutorial projects?

Tutorial projects are prepackaged demo projects that are included in jBixbe. Go to Help menu and choose Tutorial Projects. Note, it is not possible to save prepackaged projects.

How to open an existing project?

Go to File menu and choose Open Project... or click at .

How to set up a new project?

Go to File menu and choose New Project... or click at .

How to configure a new project?

Go to File menu and choose Configure Project... or click at .
Choose Launch to start a new Java Virtual Machine at the local system. Specify the main class, the class containing the public static void main() method. Give any further options for the Java Virtual Machine (e.g. -ea for enabling assertions). Build up the classpath by adding all start directories containing a package structure that should be accessible over the classpath. Remember, a zip or jar file can also be the starting point of a package structure.
If you want to attach jBixbe to a Java Virtual Machine already started at the local system or at a remote system choose Attach and give the hostname of the system and the port number of the JVM process to attach. For attaching you need the jBixbe debug agent.

How to mount, refresh and unmount sources?

Choose the Sources tab on the left side and click at Mount sources . Note, never mount a single source file, always mount a start directory of a source package structure. If such a structure is contained within a zip or jar file mount the zip or jar file.
If any changes are made on the sources during they are mounted click at Refresh to reflect the changes.
Unmount sources by selecting the source entry and click at Unmount sources .

How to start a new debug session?

Click on the Start/Continue Session or press F5. If you configure a project for Launch a new Java Virtual Machine at the local system is started. For the Attach configuration jBixbe will attach to an already running JVM at the local or at a remote system.

How to continue a debug session?

Click on Start/Continue Session or press F5. The Java Virtual Machine will be continued until an interesting event for the debugger occurs (e.g. a breakpoint is reached).

How to finish a debug session?

Click on Finish Session .

How to set a breakpoint?

Go to the Sources tab on the left and double click at the source file where you want to set the breakpoint. A static source code view will be opened. It shows you all source lines of the selected file. Set a breakpoint by a double click at a line number or with F8 for the currently selected line. Be sure to set the breakpoint at a line that also contains source code, not at an empty line.

How to observe a breakpoint?

Watching breakpoints can be done by the Breakpoint tab on the left. There you can observe all of your breakpoints. If a breakpoint is reached it will be marked.

How to delete a breakpoint?

Go to the Breakpoint tab on the left, select the breakpoint for deletion and click at Delete .

How to do source code debugging?

For source code debugging you need a dynamic source code view. There are two ways getting such a view. If a breakpoint is reached, go to the Breakpoint tab on the left, select the breakpoint, click at the thread reached your breakpoint (select right cell) and choose New View - Source from context menu. Alternatively, go to the Thread tab, select the thread for which you want to have source code debugging and choose New View - Source from context menu.

Select Step in , Step over and Step out as you know from other debuggers but note, your selection is only a setting for the dynamic source code view. Still click at to really continue the Java Virtual Machine.
The navigation operations Top , Up , Bottom and Down provide a quick navigation within call stack.
See method local variables values by clicking at Show local variables .
A dynamic source code view shows the current location of a thread only in context of the current method. In cases where you want to see the current location in context of whole source file click at Open whole source file .

How to see the output of the program to debug?

The complete output of the Java Virtual Machine that is being debugged is written to the Standard IO tab below.

How to set up user input for the program to debug?

If your program to debug expects user input, go to the Standard IO tab below and click within the text input field. After pressing Enter the input of this text field is completely forwarded to the Java Virtual Machine that's being debugged.

How to open a structure diagram?

Click at New Structure Diagram or go to the Classes tab on the left, select a class and choose New View - Structure from the context menu.

How to work with a structure diagram?

Drag classes and objects from other diagrams, from the Classes or Threads tab on the left and drop them into the structure diagram. Or use Copy & Paste. Click on a blue underlined reference within a structure diagram to include the referenced element into the diagram.
Select elements in the diagram by clicking on it and move them to the desired position. Select more than one element by holding the left mouse button pressed. Remove an element by selecting one and press Del on the keyboard.
Fold non-relevant attributes of a class to hide them by clicking at the class name. Navigate through the elements of an array by clicking at the small black triangles in front of and behind the array.
The structure diagram automatically monitors attributes for changes so every attribute is a watchpoint.

How to open a sequence diagram?

A sequence diagram always belongs to a thread so go to Threads tab on the left, select a thread and choose New View - Callstack from context menu. The sequence diagram in callstack mode shows always the current state of the thread's callstack. Select New View - Stacktrace for tracing method calls and method returns over the time.

How to work with a sequence diagram?

Drag classes and objects from other diagrams, from the Classes or Threads tab on the left and drop them into the sequence diagram. Or use Copy & Paste. Click on a blue underlined reference within a sequence diagram to include the referenced element into the diagram.
A system border (bold line on left side) has been introduced to hide elements that are not of interest. Include elements in the diagram by a click on the + within the system border.
Select elements in the diagram by clicking on it and move them to the desired position. Select more than one element by holding the left mouse button pressed. Remove an element by selecting one and press Del on the keyboard.
Sometimes it's difficult to identify which elements have to be included in a sequence diagram. In such a case use Fast Include to include the recently called elements.
Double click on a method in the sequence diagram opens a dynamic source code view for that method so you can immediately see what happens at the source code level.

How to use the Halt on event feature?

jBixbe always continues the Java Virtual Machine until an event appears that's of interest for any visible view/diagram and therefore of interest to you (e.g. a method call shown in sequence diagram or an attribute change in structure diagram). If you do not want this behavior you can instruct a view/diagram not to stop JVM if an event occurs. Click at the Halt on next event to switch that behavior on/off. This can be done for every view/diagram separately.

How to set jBixbe preferences?

Go to the Edit menu and choose Preferences.... Enable the Auto Open/Save Functionality for projects, define how many elements will be included when using Fast Inclusion in sequence diagrams and define the width of a tabulator in source code views.

How to export the debug agent?

If you want to attach a JVM to jBixbe you have to start this JVM with a debug agent. The agent comes as an operating system specific dynamic native library. Go to the Debug menu and choose Export Agent Library.... Select the platform on which you plan to start a JVM with the agent. Select operating system and machine. The default selection is your local operating system and machine. Give a directory in which the agent library will be exported. Click on Export and jBixbe will export a shared object file (libagent.so) for Linux systems and a dynamic link library (agent.dll) for Windows systems into the given directory.

How to start a Java Virtual Machine with the jBixbe debug agent?

How to display Java string objects?

The characters of a string object will be displayed in the text view (Text tab below). Simple drag a string object from any view/diagram and drop it into the text view. So you will immediately see the characters represented by the string object.

How to install a license?

Go to the Help menu and choose the License Wizard. In the first dialog choose (Re-)Install a license certificate. Click on Next, select your license file and press Install License Certificate. After installation press Next and you will see your license information.

How to verify a license?

Go to the Help menu and choose the License Wizard. In the first dialog choose Verify the current license certificate. Click on Next and you will see your license information.

Download this HowTo as zip file.