BDE2Java version 2.0 Project Final Project Report 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/qli/doc/final_report.txt Table of Contents Section 1. Introduction Section 2. Objectives Section 3. Project Design Section 4. Features of BDE2JAVA 2.0 Section 5. Detailed Design Section 6. System Requirement Section 7. Testing Section 8. Summary Section 9. Known Bugs & Limitations Appendix A - Project milestones Appendix B - bdeJava version 2.0 Documentation Appendix C - bde2Java Source Code Section 1. Introduction The "bde2java" program was originally developed by a team of UMass Lowell(UML) graduate students in the Software Engineering I course during the Spring semester of 1996. It is a Java implementation of the Block Diagram Editor (BDE), which was developed by Prof. Lechner and his students originally in C++ using X11/Motif as a GUI. It was developed using OOAD methods and can be used as a software development tool to capture the semantics of design diagrams that support CASE tools and track design changes. The original bde2java project team members were: Manuel G. Fernandes III, Daniel A. Rosato, Priya Sathyanarayanan and Hubert Sevanathan. This final report of the bde2java version 2.0 project will follow the layout of that of the original bde2java project and will reference the original bde2java project frequently. In their final report (/usr/proj3/case/96s523/bde2jav1/base/public_html/finalrpt.txt), they stated: The BDE2Java project mission was to create a Java applet that will have the same behavior of a 'display only' BDE application. The Java applet will be loaded as a standard applet embedded in an HTML document. The applet will load a BDE data (.dat) file across the internet or local area network and display the contents the same as BDE does. The implementation of BDE in Java takes advantage of Java? portability to make BDE available across multiple platforms and via the Internet. The original bde2java team did a great job in achieving their mission given the primitive state of the Java programming language and available Java developement tools. Section 2. Objectives The original bde2java project was developed using Java JDK 1.0 in Spring of 1996. The purpose of our project is to bring the bde2java code up-to-date. We were able to compile and run the original Java source code after a few changes on both PC and Compaq tru64 platforms with Sun's JDK 1.3.1 but there were 100 deprecation warnings due to the major changes that had taken place in the JDK in the 6 years since the project was originally developed. Our objective was to eliminate the deprecation warnings by refactoring the code to use the latest class libraries available in JDK 1.3.1. It was also our hope that the code refactoring would increase performance and reliability significantly due to a new design made possible by the latest class libraries and the change of event models that took place in Java from JDK 1.0 to JDK 1.1. In the interest of moving the codebase towards a distributed implementation of BDE, we decided to begin the process of separating the code into client, shared and server packages with the idea that some day client and server pieces could be run in separate virtual machines on separate machines in a client/server application Another objective along the lines of progressing towards distributed BDE was getting the code to run as an applet as the original bde2java code runs only as an application. We also hoped to test the refactored code on as many platforms as possible. We tried to make the refactored code look and feel as close to the original bde2java program as possible. We hope that future students of 91.522/523 at UML will be able to easily build upon our refactored code to expand its functionalities and fix bugs. A summary of what we have achieved at the end of the project development with these objectives in mind can be found in "section 8" of this final report. Section 3. Project Design The design of bde2java v2.0 is based on a client/server model. The client side code was refactored to move towards a Model-View-Controller architecture. All direct interactions with the filesystem were removed from the client package with the idea that eventually files will be loaded and saved to a filesystem on a remote machine. The Bde2JavaApplet class was stripped down from almost 800 lines in the original release to under 100 lines. It's only function is to serve as an entry point for launching the code both in applet and application modes. It delegates all UI creation responsibilities to the new Bde2JavaRootPanel class and all UI interaction between components to the new Bde2JavaGUIController class. A new class called Bde2JavaDataManager was created as a client side source for retrieving and saving information to the server. Eventually it is envisioned this would be done to a remote server via HTTP or some other protocol but in this release Bde2JavaDataManager just makes direct calls to Bde2JavaFileManager which performs all file interactions. The UI components were all upgraded to use Java Swing components which are more platform independent and allow for richer functionality than their counterpart AWT components. The event model was also changed to use listeners for events instead of the old JDK 1.0 model. The previous codebase was using a very expensive loop to repaint the display every 100 ms which caused a major system drag and performance bottleneck. This loop is no longer used in the refactored code and performance seems to have improved dramatically - constant screen flicker has been eliminated and system resources are no longer taxed. The server side code consists of a new Bde2JavaFileManager class along with the GIFEncoder class introduced into the project by Hua Ren in 97S523 for saving .gif files. The BDe2JavaFileManager utilizes the logic created in the original bde2java release for loading and saving bde data files and PostScript and GIF files. An enhancement to the legacy code is that file saves can now be done on a generic Vector of data passed in from any client - the old version was hardcoded to save data only from the current application. The idea behind creating this new class was that it could eventually be run in a different Virtual Machine on a remote machine for an implementation of distributed BDE. There is also a shared package which contains the two files bdeReference and bdeConstants. Code in this package is intended to be used by both client and server packages. The following diagram is a simple illustration of the bde2java v. 2.0 project. Figure 1. bde2java v. 2.0 architecture _______________________________________________________________________ ____________________ __________________ |bde2java applet |----------> | GUI Controller | |__________________| |________________| | | | | | | ______________ ______________ |Data Manager | | Root Panel | CLIENT |_____________| |____________| | | | __________________ |Workspace Panel | |________________| _______________________________________________________________________ bdeConstants bdeReference SHARED _______________________________________________________________________ bde2java File Manager SERVER GIFEncoder _______________________________________________________________________ Much of the logic from the original bde2java release was retained in this code refactoring - our object was not to reinvent the wheel but to make improvements based on the newer available class libraries. The original code to implement drawing functionality and to perform file interactions with the filesystem was retained with very few changes. Section 4. Features of BDE2JAVA 2.0 The bde2java 2.0 program retains most of the features of the original bde2java program and includes some enhancements and bug fixes as well. Basic functionality retained from the original release include the ability to create new diagrams and save them to data files on disk and open previously created data files for editing. Diagrams can also be saved in PostScript or GIF formats. Basic drawing functions such as creating and manipulating Nodes, Links, BendPoints, Text and Captions have also been retained from the previous release. One enhancement that has been added in v 2.0 is the ability to save and open data files with either .dat or .bde file extensions. The original release only recognized .dat files. A bug in the file interaction mechanism of bde2java 1.0 was also fixed. The original release popped up a SaveAs dialog to save new data files which gave the appearance of allowing the user to select a directory to save to but the reality was that only the filename was being extracted in the code and thus all files were saved to the user's current working directory. bde2java 2.0 has corrected this behavior and allows users to save their data files to any directory on the filesystem. This behavior is also true for PS and GIF files - the previous version did not allow for directory selection but v 2.0 now does. Another significant enhancement added in v2.0 is the ability to run the code both as an applet and an application. The original release did not function as an applet. The significance of this step is that Web users can now use the application without having to have the source code compiled and installed on their systems - they can just browse to a URL where the code is available and run it from within their Web browser. A few small enhancements were made to the menus - accelerators and mnemonics were added and all unimplemented features were disabled. A small bug in the display of the "About..." dialog was also fixed - the dialog was being sized improperly so that all of the text was not readable but it now is large enough so that none of the text is cutoff. Section 5. Detailed Design Please reference a set of Xref-generated html files under: /usr/proj3/case/02f522/bdejavaProj/qli/doc/html for design and implementation details. Section 6. 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 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. 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 7. Testing The bde2java v.2.0 program has been tested on both Windows and UNIX platforms in both the application and applet modes. While running bde2java v2.0 in applet mode through a web browser, you may be prompted to install Java plugins v1.3. if the machine you work on don't have the plugin yes. It may take 20 more more second for the applet to load depending on your connection speed. 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 A number of bugs have been found through testing. Some of them have been fixed. Some of them we don't have time to fix are mentioned in section 9 of this report. Section 8. Summary It's been a very interesting project to work on. We have been working together as a team effectively as a team in developing, testing and documenting the project. We are very pleased that we were able to make significant progress in upgrading the bde2java program. The bde2java program is more robust and efficient due to much improved Java support libraried and development tools than its original version. We have gained a lot more understanding of the BDE program and the OOAD aspects of software project development than we has at the begining of the project. This have been a challenging yet rewarding project for us to carry out through the Fall semester. As we look back, we have realized most of the objectives we had in mind at the start of the project. The bde2java v2.0 could be an very interesting program for future OOAD students to improve upon. There are however a number of defects and limitation we don't have time to resolve. They are listed in the next section. Section 9. Known Bugs 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 - Project milestones Milestones Date bde2java 2.0 project team formed Nov. 6, 2002 Project proposal submitted Nov. 27, 2002 GUI prototype completed Nov. 30, 2002 First working applet with minimum functionality completed. Testing and debugging started. Dec. 5, 2002 Began writing final report and user guide Dec. 11, 2002 Successfully reused many old drawing function Dec. 14, 2002 Code development completed Dec. 16, 2002 Testing and debugging completed Dec. 17, 2002 Final report and user guide completed Dec. 18, 2002 Appendix B - bdeJava version 2.0 Documentation A user guide of the bde2java v. 2.0 program can be found at: /usr/proj3/case/02f522/bdejavaProj/qli/doc/user_guide.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/qli/doc/html Appendix C - bde2Java Source Code The source code of the bde2java v. 2.0 project can be found at: /usr/proj3/case/02f522/bdejavaProj/dshea/src