License
=======

This software is covered by the GNU public license.  Feel
free to distribute this software to your friends!


Installation for JBuilder 3.0 Foundation or JBuilder 3.5 or JBuilder 4.0
========================================================================

(1)  Copy jrefactory.jar into <jbuilder>/lib/ext,
    where <jbuilder> is the directory that you installed
    JBuilder into.  On my machine, <jbuilder> is c:/jbuilder35.

(2)  Launch JBuilder.  The system will prompt you to find
    the src.jar file that comes with the java development
    kit from sun.  You can browse to a directory that contains
    the .java files for the JDK that you are working with.

    Select the src.jar file or directory containing the
    source code, and press OK.

    This process is very disk and CPU intensive.  On my
    machine at work (333 MHz Pentium II, 128 Meg of
    RAM, Dell Computer running Windows NT 4.0 Service
    Pack 5), this operation takes about 2.5 minutes.
    The hard disk light will be running continuously
    during this process.

    This step will allow the JDK classes to appear in the
    class diagrams.  It is also required for some of the
    refactorings.

(3)  Once JBuilder has started, select "Load Refactoring
    Metadata".  A dialog box labeled "Loading source files"
    appears in the upper left corner of the screen.

    The interior of the "Loading source files" dialog box
    may take a few seconds to paint.  This is because the
    system is doing a lot of work to load JBuilder and
    the source files for the UML class diagrams.

    The box will first say "Loading JDK" with a red
    progress bar under it.  Then it will say "Loading <dir>",
    where <dir> is the name of the directory you entered
    in step 3.  The progress bar is now blue.

    When the "Loading source files" dialog box disappears,
    you are ready to view UML diagrams in JBuilder and
    perform refactorings.

Note:  JBuilder 3.0 Foundation for Windows has a bug that only
    allows you to load a single open tool.  I recommend upgrading to
    JBuilder 3.5 foundation.  You can also modify the JBuilder.bat
    file to manually include the open tools.

Normal Launch
=============

This is what happens when you launch JBuilder for the second
and all further times.

If you had a UML package diagram open at the time that you
closed JBuilder, the following will happen:

(1)  Upon launching JBuilder, the dialog box labeled "Loading
    source files" appears.  First it appears with the label
    "Loading JDK" with a red progress bar.  Then the label
    changes to "Loading <dir>", and the progress bar is blue.

(2)  Once the "Loading source files" dialog box disappears,
    the system is configured to display UML class diagrams
    and preform refactorings.

Note that this will greatly reduce the speed that JBuilder
launches.  However, you will be instantly ready to view the
UML diagrams and perform the refactorings.

If you do not have a UML diagram open, JBuilder will launch
much more quickly.  However when you first open a package.uml
file or select the "Reload UML Diagrams" menu option, the
refactory will load the required data.  The dialog box will
appear as described above.

Reformatting source code
========================

This system provides a mechanism for reindenting your
source code.  This system also inserts appropriate javadoc
comments into your code.

The primary way to do this is to press Control+Shift+P
when viewing the source file in the editor pane.  The
alternative is to use the menu:

(1)  Open a .java source file that can be compiled.

(2)  Select JRefactory from the JBuilder menu

(3)  Select Pretty Printer

     The file is reformatted, and your cursor jumps to
     somewhere near the end of the file.

Note that if the source code would not compile as it
stands, you will see a dialog box that says "Unable
to Parse the File".

Configuring the Pretty Printer
==============================

The configuration for the pretty printer is contained
in a file called pretty.settings.  This file is located
in <home>/.Refactory.  This directory and the default
pretty.settings file is created automatically.

The easy way to configure it is to select the menu
item.  When you select save, the java source code to
the right is reformatted.  Alternatively, you can
edit the pretty.settings file.

<home> is ~ for developers using Linux or Unix based
systems.  For developers using Windows NT, <home> is
c:/winnt/profiles/<yourname>.  For developers
using Windows 95/98, <home> is c:/windows.  For developers
using Windows 2000, <home> is C:\Documents and Settings.

Before each configuration is a brief description of
what effect making the change has on the system.  Feel
free to change any of them and watch the effects.
If you don't like the results, don't save it to the
disk.

The configuration is reloaded each time you select
Pretty Printer from the menu.

Displaying a UML diagram
========================

To display a UML diagram, you:

(1)  Select JRefactory from the menu

(2)  Select New UML Diagram from the drop down menu

(3)  Select the package you want to view in the list
    box and press OK

    A new node appears in the project window called
    Class Diagram.

(4)  Double click on the node in the class diagram

    The editor pane now contains the class diagram.

Note that the information about how to display the
class diagram is stored in a file called package.uml
that is stored in the appropriate directory.  Thus
there is a second way to view a class diagram.

(1)  Select File from the menu

(2)  Select Open from the drop down menu

(3)  Select Open File from the next menu

(4)  Browse to the package that you want to see the
    diagram for.  Open the file called package.uml

You may also add package.uml files to the JBuilder
project.

Known Bug:  The tab across the top does not always
list the package name.  Sometimes it instead lists
the class diagram as "Unknown Package".  I'm working
on that.

Performing a Refactoring
========================

The real power of this system is that by changing
the UML class diagram, your source code gets updated.
Here is a generic description of how the refactorings
work:

(1)  Find the class that you would like to change

    For instance, let's say that we have a class
    named "BadName" and we want to rename it to
    be "BetterName"

(2)  Right click on that class

(3)  Select the refactoring to be performed

    If you clicked on the name of the class, then
    you just see two options:  Type Refactorings
    and Metrics.  Mouse over Type Refactorings.

    The pop up window shows Rename Class at the
    top of the menu.  Click on Rename Class.

(4)  A dialog box appears and requests more information.

    In our example, the dialog box prompts you for
    the new name of the class.  Enter the new class
    name and press OK

(5)  The system starts updating your source files.

    Note that if a file that contains source code is
    read only and that file needs to be changed by
    the refactoring, you will be prompted to check it
    out of your version control system.

(6)  The class diagram shifts and wiggles as it reloads
    the files.  You can now browse through your source
    code to see the effects of the change.

Printing
========

If your system has the JDK 1.2 printing features implemented,
then you will be able to print a file.  The JRefactory code
is able to print any text file with line numbers.  If the
file has an extension that ends with "ml" for instance
.xml or .html, then it will print the file with some
syntax highlighting.

If the file has an extension .settings or .properties, it
will print the file with highlighting.  Lines that start
with # will be considered comments, and the first part
of the line will be bold with everything after the =
in a monospaced font.

If the file is a class diagram, the diagram will be printed.

To print, simply open the file that you want to print.
Select JRefactory then Print.


Comments or Undocumented Feature Reports  :-)
=============================================

If you like the software or if you would like to have the
software improved, feel free to send me an e-mail at
seguin@acm.org.

If there is a bug, then please describe what you were doing
when it occurred.  Also, please send me any stack traces
that appear in the JBuilder shell window.  (When I launch
JBuilder in Windows NT, I get two windows:  A Command Shell
and the JBuilder editor.  The command shell contiains the
exception traces that I need to help debug the problem.)

My next goal is to get some method refactoring going.  The
first one is push up method and push down method.  (See
Refactoring by Martin Fowler.)

Since this is open source, feel free to add more functionality!
I'll be happy to help show you where to add a particular feature.