BDE2Java version 2.0 Project User Guide Dec. 18, 2002 Project Members: Dan Shea Qiang Li Instructor: Dr. Robert Lechner Course Title: Object Oriented Analysis and Design Path: /usr/proj3/case/02f522/bdejavaProj/doc/user_guide.txt Reference: www.cs.uml.edu/~lechner/bdeUG2htm/bdeUG.ppt by Prof. Robert Lechner rev. 97/9/2 (some of the BDE user guide material are used since we tried to make bde2java look and feel like the original BDE program) Table of Contents Section 1. System Requirement Section 2. Compiling and Running bde2java v. 2.0 Section 3. Basic Drawing Functions Section 4. File operations Section 5. Known Defects Appendix A - bdeJava version 2.0 Documentation Appendix B - bde2Java Source Code and Executables Section 1. System Requirement The major system requirement for building the source code for bde2java is the installation of Sun's JDK1.3.1. While other versions of the JDK may work, the code was refactored and tested in JDK 1.3.1 and thus other versions may or may not support the current features implemented. For running the code as an application, the only major system requirement is that Sun's JDK 1.3.1 be installed and that either the java or javaw executables are used to run the code (javaw is preferred as it eliminates the need for a companion DOS window). Users must remember to use the full package name when launching in application mode. The example below assumes the user has navigated to a "classes" directory in which the compiled classes are installed in their package directories (i.e classes/bde2java/client, classes/bde2java/shared and classes/bde2java/server): javaw bde2java.client.Bde2JavaApplet To run the code in applet mode, the user must either create a custom HTML file which will launch the applet or use the one provided in $CASE/02f522/bdejavaProj/dshea/bin/Bde2Java2.html. This HTML file must either be placed in a directory similar to the "classes" directory described above which has the compiled classes in their proper package subdirectories or it can be placed in any directory along with a BdeClient.jar file which contains all of the class files. A BdeClient.jar file also exists in $CASE/02f522/bdejavaProj/dshea/bin. Clients must use a Web browser that supports JRE1.3.X in order for bde2java v. 2.0 to function properly. One such browser/JRE pair that fully supports bde2java 2.0 is Microsoft Internet Explorer 5.x/6.x with Sun's Java Plugin v. 1.3.X installed. Other browsers/JRE pairs might be possible but the code was developed and tested exclusively in the IE/Java Plugin environment. If the client does not have Sun's Java Plugin installed already, the Bde2Java2.html file will attempt to redirect them to Sun's Web site to install the Win32 version of this plugin. Clients not using Win32 machines will have to either install the plugin beforehand or modify the .html file in order to install the plugin appropriate for their environment. If users running in applet mode wish to interact with their filesystem (saving and opening files), they must make changes to the java.policy file used by their JRE similar to the following: grant codeBase "http://www.cs.uml.edu/~dshea/*" { permission java.io.FilePermission "C:\\", "read,write"; permission java.io.FilePermission "C:\\*", "read,write"; permission java.io.FilePermission "C:\\-", "read,write"; permission java.io.FilePermission "${user.home}${/}*", "read,write"; permission java.util.PropertyPermission "user.home", "read"; permission java.lang.RuntimePermission "modifyThread"; }; The above snippet was added to the java.policy file on a Win2K OS in order to allow file access to the applet which was loaded from the URL http://www.cs.uml.edu/~dshea/Bde2Java2.html. The java.policy file on this machine was located at "C:\Program Files\JavaSoft\JRE\1.3.1_02\lib\security" - other JRE's and operating systems may differ in their java.policy file location but the path should be similar. [RJL 040223: On my IBM WinXP PC, it is here:] ======================================================= C:\>dir "C:\Program Files\JavaSoft\JRE\1.3.1_09\lib\ecurity Volume in drive C is IBM_PRELOAD Volume Serial Number is ECB6-8A75 Directory of C:\Program Files\JavaSoft\JRE\1.3.1_09\lib File Not Found C:\>dir "C:\Program Files\JavaSoft\JRE\1.3.1_09\lib\security Volume in drive C is IBM_PRELOAD Volume Serial Number is ECB6-8A75 Directory of C:\Program Files\JavaSoft\JRE\1.3.1_09\lib\security 12/01/2003 12:46 AM . 12/01/2003 12:46 AM .. 08/05/2003 09:03 AM 7,365 cacerts 08/05/2003 09:03 AM 2,358 java.policy 08/05/2003 09:03 AM 4,632 java.security 3 File(s) 14,355 bytes 2 Dir(s) 27,749,945,344 bytes free ============================================== ] One note of caution: The above addition to the java.policy file grants ANY code located in the http://www.cs.uml.edu/~dshea/ directory full read/write access to the local filesystem. Modifications to the java.policy file should be done with caution and only grant access to trusted code. Section 2. Compiling and Running bde2java v. 2.0 Java JDK 1.3.x is recommended for compiling bde2java v2.0. The directory "/usr/proj3/case/02f522/bdejavaProj/src" ("dshea/" omitted-RJL) contains all the source code for bde2java v.2.0. The files are organized into three packages: bde2java.client, bde2java.shared and bde2java.server. Separating the files into packages this way was done with the thought of progressing the codebase towards a future client/server implementation. The bde2java program can be run in both application and applet modes. The source code can be compiled on both Windows and UNIX platforms. To run as an applet, place both the Bde2Java2.html file and the BdeClient.jar file located in the directory "/usr/proj3/case/02f522/bdejavaProj/bin" ("dshea/" omitted-RJL) into a common directory and navigate to Bde2Java2.html in Microsoft Internet Explorer 5.0 or greater. The applet requires JRE 1.3.x or greater to run properly and will attempt to install Sun's Java Plugin 1.3.1 (Win32 version) if it is not already present if an Internet connection is available. Other browsers and versions may work but are untested as of this release. As of the end of 02f522, the applet can be run from the following Internet URL for the time being: http://www.cs.uml.edu/~dshea/Bde2Java2.html [RJL 040223: Try .../~lechner/COOL-BDE/bde2java2/bin To run bde2java v2.0 in application mode, just type the following command from the "classes" directory after the source code is compiled: javaw bde2java.client.Bde2JavaApplet Section 3. Basic Drawing Functions The following is the text version of "bdeUG.ppt" with some modifications Bde File Processsing New Open Save SaveAs Print Exit To see bde’s pop-up FILE menu, click the leftmost button in the top-row menu of bde’s main window. File ... Options Object- Oriented Drawing Menu bde drawing canvas window Bde’s O-O Drawing Menu Node Link Bendpoint Text Graph Create Move Delete Resize Restyle Restyle Sub-menu (Restyle options depend on the selected class: e.g., node shape, link pattern, or diagram type. Class + Method determines the initial state for all canvas drawing operations. Each operation is applied to exactly one mouse-selected object. Bendpoints and Text operations require prior selection of a node, link or caption parent. (Bendpoint and Text items are TBD classes.) (Two Radio Button Sets at the left of bde’s drawing canvas.) Bde Node Operations To Create a node click at its desired center position. (Clicking means pressing mouse button 1 down then up without moving it.) To Move a node, click to select and highlight it, then drag to new location. (Dragging means moving the mouse with mouse button 1 held down.) Delete a node by double-clicking within its border. (Node Delete is not permitted until all attached links are deleted.) Resize a node by clicking to highlight it then dragging to a new size. (After node resize, attached links retain their bendpoints and shape, and internal text remains left-justified.) Restyle to select a non-default node shape from the Restyle submenu. Create a link by dragging the mouse from a source node to a destination node. (Link endpoints will be on node borders.) Delete a link by double-clicking on it (link text is deleted also) Restyle arrow head/tail direction, width and pattern options on each link segment (since 96su523/fjara project). Use Reverse to cycle through arrow head/tail option (to be merged with Restyle). Use Restyle to select a non-default line pattern or width. Set new default style from the Restyle menu (to be merged with Reverse.) Bde Bendpoint Operations Bendpoints are points where links start or end, change direction or drawing style. For bendpoint operation, first select a link; this will highlight the link and its bendpoints, and prevents selecting the wrong type of object. Then: Create a new successor bendpoint by clicking on an existing one. Move a bendpoint by dragging it. (Endpoints are not movable.) To edit text, first select a node, link or graph caption box. This highlights the 'parent' object with which the text is associated. All text is located relative to, and moves with, its associated object. If a line of text is dragged, its successors (in creation order) belonging to the same parent are dragged along. Motif text is edited by using arrow keys to move the cursor to the left, then deleting to the right. (Edits after entry are TBD.) After selecting the method and highlighting the parent : Create a text item by typing into the Motif-style text widget. Move a text item after creation by dragging it (e.g. label2) Successor lines move with the one dragged (e.g. Label3). Delete a text item by clicking on it. (Succcessors may also be deleted). Add more text to a Node by changing NodeAttribute on the top-row Options Menu to HA and repeating Create Text. Add more text to a Link or a Graph Caption by repeating Create Text on the same parent. Bde Entity Types FI Holds file path and date information (TBD) FO Holds font table info (X11, menu, PostScript) HG Identifies one diagram or Graph CG One Caption (block) of its parent HG GX One text line of its parent CG HN One Node (block) of its parent HG HA One text line of its parent HN HL One directed Link between two HN’s HI One link label of its parent HL HP One ‘bend’Point of its parent HL GD Graph Defaults - diagram drawing styles XB Text Block: SuperClass of GX and HA. [Ref: 96f523/bdecode/cparisi] (XB requires a schema change.) Section 4. File Operations Bde File Menu - 1 New/Open/Close/Print As GIF/Print As PS New opens a new unnamed file and its first graph or diagram. Open displays a File Selection dialog and prompts for a file to open. If successful, it displays the file on the drawing canvas for editing. Close clears the drawing canvas - any unsaved data will be lost. Print As GIF/Print AS PS opens a dialog for selecting a directory in which to save the file(s). After a directory is selected a PostScript or a gif version of the current graph will be saved to a file named .{ps or gif}.* HGid is the graph table identifier of the diagram currently displayed. Bde File Menu - 2 Save/SaveAs/Exit Save saves a named file, overwriting a previous file by that name. It will not save a new file without a name - use SaveAs for this. SaveAs prompts for a name by which to save a file being edited. All diagrams in the file will be saved, whether changed or not. Exit terminates the editor. If bde crashes, the database is usually saved to a file called bdeabort.dat Section 5. Known Defects and Limitations Since most of the business logic of the original bde2java release was retained, some bugs and limitations inherent in that release also exist in bde2java 2.0. The most notable limitation retained from the original release is that only one graph can be created per new file. The intention is for BDE to allow the creation of multiple graphs per file and then allow the user to switch between graphs by using the graph names listed in a combobox. The code does have much of the logic already in place for handling multiple raphs per file (the save and open file logic which processes the data files can handle multiple graphs) but the UI right now replaces the current graph with a new one each time the New option is selected from the File menu. There is also a bug in the Text creation/editing logic which remains in this release. The code uses a simple constant to toggle between states of ACTION_PENDING and ACTION_NOT_PENDING which determines whether or not the Text editing dialog should be displayed. But if the user opens the Text editing dialog and closes it by clicking on the X close window icon instead of the OK button, all text editing functionality will be lost for the remainder of the session because the application will be stuck in an ACTION_PENDING state. There also seems to be a harder to identify problem with text rendering. At times multiple versions of text are echoed to the screen and these extra versions don't respond to Text Delete actions. Lack of time has prevented further investigation into this problem. BendPoint functionality is sketchy - while bendpoints located at Node endpopints can be created and moved, the functionality to create internal bendpoints seems to have problems as most times mouse clicks are not recognized. Appendix A - bdeJava version 2.0 Documentation A final report of the bde2java v. 2.0 program can be found at: /usr/proj3/case/02f522/bdejavaProj/doc/final_report.txt A set of html files with cross reference of the bde2java 2.0 source files can be found under: /usr/proj3/case/02f522/bdejavaProj/doc/html Appendix B - bde2Java Source Code and Executables The source code of the bde2java v. 2.0 project can be found at: /usr/proj3/case/02f522/bdejavaProj/dshea/src The compiled code and required .html file for running as an applet is located at: /usr/proj3/case/02f522/bdejavaProj/dshea/bin You can run the program in application mode in two steps on the CS dept's Tru64 system: % cd /usr/proj3/case/02f522/bdejavaProj/qli/classes % run_bde2java