Jacob Mini-Tutorial and FAQ

 

Jacob Mini-Tutorial


Just bring me to the FAQ.

The purpose of this mini-tutorial is to get new Jacob users started and to demonstrate it's basic features.

Introduction with Example Project

After starting Jacob for the first time it opens an empty project named 'tutorial'.  There are already two Java source files inside the jacob/tutorial directory which we want to insert into our project. Both files belong to the package 'jacob.tutorial'.

Therefore use Jacob's menu at 'Edit->Add Package...', type in 'jacob.tutorial', and press 'OK'.

Now, this package should be listed in the top list window. Clicking  on this String should reveal the names
of two classes in the middle list window ('Main' and 'World').

If you properly set up Jacob then clicking on one of these two class names should load the appropriate source code  into Emacs. In the bottom window you see the string "<parse>". Click on it and Jacob will parse the current source file and display the methods of the current class. In this case there exists only one method. Of course, now you can use this/these method(s) for navigation too. The height of each list window can be changed. Simply click on a bar between two lists and move it up or down. When the project gets saved, the list window heights will be stored for each project individually.

It's time to save your project file ('File->Save') and create a makefile ('File->Create Makefile'). Your project file is stored at .../jacob/tutorial/tutorial.proj and the makefile is likewise stored in the same directory.
You can take a look at this makefile with 'Edit->Makefile'. Now go back to one of the source files inside Emacs and start the compile process with the elisp function compile, which in fact starts make. This should compile both java source files.

BTW this is the elisp code I use to compile.

(defun my-compile ()
       (interactive)
       (if (string= major-mode "java-mode")
           (progn
                  (compile "make all")
                  )
           )
       )
(global-set-key [f10] 'my-compile)
Next you want to start and test this application from inside Emacs. First Jacob must know which of your project classes is the one with the public static void main(String[]); routine. This can be specified at the Project Settings Dialog ('Edit->Project Settings...'). Press Select News and select 'Main'. Now recreate the makefile ('File->Create Makefile'). When looking again at the produced makefile, there is a new section run:.  To execute the hello world
java application you must start make with the run parameter. To do this from inside Emacs I have the following elisp function bound to a key:
(defun my-run ()
       (interactive)
       (if (string= major-mode "java-mode")
           (progn
                  (shell-command "make run &")
            )
        )
 )
(global-set-key [f9] 'my-run)
Now hit this key and you should see the 'hello, world' output.

Navigate to Method Callees

After you compiled your project you have another option to navigate through your project sources. (Make also sure you parsed both example class files, Main and World, before proceeding.) Now select method Main.main(..) as a starting point. A click with the right mouse button invokes a window titled "Method Callees". It is still empty. Click on the "<parse>"-button inside and a list with each method invoked inside Main.main(..) will be created.

We use this window now to jump from method to method until we get out of the project's scope. Click now on jacob.tutorial.World.World(). Emacs jumps to that method and also selects it in Jacob. Press again the "<parse>"-button and select java.lang.Object.Object(). Oh, bad luck, in Object.java is no constructor defined :=(. Anyway, I believe you can surf much longer  through your own source files :-).

A New Project

For example, you want to have a project named test with source files in a package named test either.
Then, goto c:\java_apps
do
mkdir test
use Jacob "File->Open..." and goto c:\java_apps\test
and fill in the name test.proj and press ok. Now the project test.proj is opened into Jacob. (The project file itself will be created for the first time when you save this project once.) But it's still empty.

 So first set the project's classpath under "Edit->ProjectSettings..." and then "change classpath". Change the classpath to c:\java_apps;c:\jdk1.1.5\lib\classes.zip, press ok everywhere in this dialog and goto "Edit->Add Package..." and type in simply "test" and press ok.
It says then: "warning: empty package" but that doesn't matter.

 Now you need some java classes. Either copy some into the test directory and make sure they contain the package test; statement, create new source files from scratch yourself, or use the "Edit->New Class..." Class Wizard to create a class template file. If you use the class wizard, the new class is automatically included into your project. in the former case, you must include them with "Edit->Add Classes...". Then, jacob scans the test directory and will find every .java file and includes it into the test.proj project. Now would be an appropriate time to save your project data.

Ok, lets recall the steps to create a new project:

1. open a new project which then is still empty
2. set the classpath for this project all right
3. add a package to the project
4. fill the package with source files
5. save your project data ("File->Save")
---
More to come ...

Jacob FAQ

1) Installation 2) Usage

1) Installation

1.1) ...java.lang.NoClassDefFoundError: com/sun/java/swing/JList

After invoking Jacob in the command line the following error occurs:
java -classpath ..;D:\jdk1.1.3\lib\classes.zip;D:\swing-0.5.1\swing.jar jacob.Main

...java.lang.NoClassDefFoundError: com/sun/java/swing/JList
        at jacob.Controller.<init>(Controller.java:318)
        at jacob.Main.main(Main.java:17)

Ans:
There is a possibility that the classpath is not set correctly, so the swing.jar archive can't be found. But more likely it is, that during the download the swing.jar archive got broken. This does regularly happen when using Netscape for downloading bigger files. You can test if this happened with an unzipper, for example 'jar tf', 'unzip -t' or 'winzip'. Just try to list the content of the swing.jar file. If that is not possible and results in an error message, you know it got corrupted.

1.2) All class files have lower case names on Unix and the JVM can't handle them.

It appears that a number of Jacob classes are in .class files that do not match the case of the classes they contain ie.

jacob.Main is in /jacob/main.class

The java VM complains that it cannot find this file. If I mv jacob/main.class to jacob/Main.class, this class loads fine, but the VM then fails to find additional classes. Obviously I do not want to go through all .class files and change them.

Ans:
This is either because you use an old unzip version (your unzip version should be something around 5.30), or in some shell configuration file (etc/profiles) might be an alias defined for unzip like "alias unzip='unzip -L'" which changes the normal unzip behaviour to extracts all files with lower case letters by default. You might also try the -U option for upper case letters.

1.3) How do I report bugs or other problems?

Ans:
Of course just send me a note. Any feedback will be very much appreciated. I try my best to make Jacob as bugfree as I can, but your help will be needed too. I know you don't have the source code to debug Jacob yourself; but in case you get hit by a serious bug like a crash with a runtime exception or so, you could execute Jacob with the command line option '-debug'. That creates a lot of additional output (don't hesitate to send it all). Maybe that will help me to locate the bug.

If you want to get a new feature into Jacob, feel free to go into details describing it. Otherwise I might not get the idea. :-)

1.4) I am new to Emacs. How can I configure it suitable to Java programming?

Ans:
Well, if you are completely new to Emacs first go read the Info documentation for it (Ctrl-H I). That will keep you busy for a while ;-).  Then to setup Emacs for Java I recommend checking one of the two web sites below which solely focus on this topic.
 
 
Just for the completeness sake and because sometimes people ask me for my own personal .emacs file (I used it on NTEmacs, does not work on XEmacs), here it is together with a Java font lock elisp file (java-f-lck.el), which is a modified version of Mitch Chapman's java-f-lck.el file. But be warned, it's all hacked, undocumented, and sometimes preferences are hard coded (like 3 spaces default indentation for tab stops) etc.

2) Usage

2.1) How do I create a new project?

Ans:
See mini-tutorial A New Project.

2.2) How do I add Java source files that do not belong to a package?

Ans:
Use the virtual package '.' instead. Jacob can have one "no name" package. When adding a Package with the name "." (just a single dot), it includes all .java files from the first directory of the project's classpath. So, make sure your classpath is set the way you need it. If you want to add the file C:\java_apps\test\Test.java, make sure C:\java_apps\test is the first element in the project's classpath, add the new package '.' and you are done.

2.3) How can one common copy of Jacob be used by different users, so that each user can invoke Jacob with its own personal '.ini' file?

Ans:
By default Jacob loads the "jacob.ini" file located in jacob's "main" directory. You can start Jacob with:
      -inifile /absolutepath/personal.ini
Either use it in the batch file or in the command line.
You can also use one project from different machines/locations. You just need to update the project each time you change your location and set a different classpath once on each location. Ok, but this is another issue.

2.4) When parsing Java files for methods, Jacob seems to show only a portion of the method signature, such as "nt,String)" instead of "func(int,String)".

Ans:
This problem arises when your source code is located physically at a different place than the logical structure suggests. If you have a class foo.Bar, make sure, that:
 
a) your source file is located in the right directory, that is
.../foo/Bar.java
and
b) your source code contains the statement:
package foo;
 
The reason for this is, Jacob parses the source code, and uses also the package/directory structure to get the method information AND to present it (in this case package information gets cut off so only the method signature gets presented in the the method window). If the logical and physical package structure is not the same, the result is the observed.
 
As a result, always make sure your source files are in located at the place you would expect just by just having package and class names. Yes, this means you can't use the -d flag for javac together with Jacob.


Back to Jacob's main page


Chr. Clemens Lahme, email to: Clemens.Lahme@gmd.de