$PH/08s522/bde2javaUserGuide080123.txt - RJL080123 (was bde2javaDemoGuideAndTestResults.txt) ===================================== This report describes bde2java, a Java-based block diagram editor (BDE) which develops models that can support automatic code generation. The bde2java version differs slightly from a parallel bde Unix version, but both can create and edit the same data-compatible files of design diagrams for UML-related class, state, and interaction models at class- or object-level. This note summarizes how BDE editing works on the server at UML/CS and how to run it from any PC web browser. It includes hints for using bde2java, and how bde2java differs from bdeUnix, a XWIndows-based application. It gives an example of a diagram file drawn with bde2java that is saved in BDE's common diagram file format and/or printable .gif and .ps. An earlier bdeUnix User Guide (.ppt or .html) is also relevanti; it is accessible at http://www.cs.uml.edu/~lechner/06f522/COOL-BDE/BDEUserGuide2005/ CONTENTS: 1. UML/CS COOL Framework for Model-Driven Development 2. How to run bde2java remotely across the web 2.1 Java Console Log History 3. How to edit diagrams with bde2java 3.1 File Open works like most GUI's 4. BDE drawing conventions for special diagram types: 4.1 State models with self-loops 4.2 Class diagrams with inheritance 4.3 Bendpoints for multi-segment links 4.4 Multi-line Text in Nodes and Captions 5. Example of Block Diagram creation with BDE 5.1 File/New File 5.2 Caption Create/Move 5.3 Text Create/Move 5.4 FILE/New Graph (Graph Create) 5.5 FILE/File Save[As] 6. BDE File Format and Data Model 6.1 Example BDE diagram file 6.2 Saving a Diagram File Appendix A: Java Console Display of Editor Progress 1. UML/CS COOL Framework for Model-Driven Development ========================================== The UML/CS COOL Framework contains 3 inter-related components: BDE, GEN and LCP. Each of these has its own home page link under ~lechner/06f522/COOL-* . This report is focused on BDE. BDE has two versions: bde for Unix is written in C++ for the Unix XWindows GUI, and bde2java with (35K lines of) Java source code. LCP is a simple event dispatcher and statew model interpreter written in C. LCP's read-only tables and BDE's persistent diagram database.are both supported by code libraries produced by GEN. GEN is a back-end database code generator that supports any modeled application with an application-specific RDB. GEN is the back-end database support component of COOL. Its first version, chgen. generated 'C' code and header [ch] files from relational data models. Chgen translates an EERD data model (Entity-Relational Diagram, extended with inheritance). into a 'C' source code library for database persistence, navigation and access. Later and less complete versions of GEN called gencpp and genjava, produce C++ and Java code, respectively.) The circle of dependence is completed by using BDE to draw EERDiagrams from which a converter (bde2sch) can provide input to any GEN.version. [In fact, GEN itself depends on a metametamodel that specifies how it stores input application tables and attributes. We have used bde to draw and bde2sch to convert this metametamodel into code inside a bootstrapped version pf chgen.] LCP's tables drive its event-dispatching interpreter. They are extracted from state and network models which represent event and control flow for (the dynamic behavior of) any model-driven application. Several demos show how LCP supports rudimentary interactive distributed processes. E.g., BDE for Unix class method code has superimposed state models that specify how graphic editing actions react to GUI-event inputs. Bde2java is currently independent of GEN and LCP but it uses bde's file format. BDE can draw data [class] models that GEN can translate to code that supports persistent database management. BDE can also draw state diagrams and network models for runtime interpretation by LCP's event-driven concurrent process simulator. Programmers who follow strict naming conventions can write atomic state action routines which caan be compiled and linked to the runtime LCP interpreter. The data model for BDE's diagram database is generic to the 2D graph-drawing application. Its standardized format is recognized by all GEN versions. The current version of BDE's data model is specified as a GEN-parseable schema [.sch] file at http://www.cs.uml.edu/~lechner/06f522/COOL-BDE/bdeUG_2000/bdeschema/ and is the second EERD diagram at http://www.cs.uml.edu/~lechner/06f522/COOL-BDE/bdeUG_2005DataModels.mht All three COOL components GEN, LCP and BDE are designed to provide proof of concept for applying COOL framework. code generation principles to themselves. I.e. they 'practice what they preach'. The intent of the COOL Framework architecture is to create all design diagrams for a specific application such as graphic computations in the bdeUnix editor in a single design file. [TBD: Introduce namespaces to resolve name clashes among independently designed components .] Our goal is to append all design diagrams for a specific application (e.g. the BDE editor) in a single design file. This file can be placed under concurrent version control (e.g. CVS) to capture its revision history.. (CVS can support concurrent editing on distinct diagrams within a file.) TBD: Broaden CVS use to support remote multi-user checkouts and commits.] An example of an application-level diagram file is our simulator for the Juice Plant Case Study in Shlaer & Mellor's insightful book: "Object Life Cycles: Modeling the World in States", Prentiss-hall 1992. The JP2html Demo link is: http://www.cs.uml.edu/~lechner/06f522/COOL-LCP/JP2html/public_html/ It includes data models for COOL's BDE and LCP support context, as well as data and state models for the JuicePlant's process control functions. JP2html diagrams were generated by [an early version of] bde for Unix. They include clickable hotspots that link to sub-diagrams or text file anchor points. Bde drew these JP2html diagrams and bde2htm converted them to web-browsable form. Switching among diagrams is easy in BDE. The current diagram unique identifier or pkey HGid is displayed in a box above the OOMenu. Clicking it opens a popup list to select any other diagram.in this file. [TBD:Implement bdeUnix's display of the entire HG-table with title etc., not just the object's pkey or oid.] 2. How to run bde2java remotely across the web: =================================== On 2007/12/08 I created a new 2-diagram file using bde2java atUML/CS, saved it locally as C:\...\My Documents\bde2javatest071208.bde. and copied it to www.cs.uml.edu/~lechner/06f522/bde2javatest071208.bde You can modify this diagram by saving it locally, pointing your browser at http://www.cs.uml.edu/~lechner/06f522/bde2java2 and .clicking 'Run Application'. (Bde2java documents and Javadoc API info are also accessible from this menu.) 2.1 Java Console Log History: ------------------------------- The Java console is a separate window used for debugging. A Java console window logs BDE actions while the editor runs. It may help you resolve unusual access problems or delays. Appendix A contains extracts from the java console log of my test run below. My extract from the Java console log in Appendix A ends abruptly. After I approved remote access to my PC, it down-loaded a Bde2JavaClient.jar file (133KB). Bde2java source code is divided among client, server and shared sub-directories. Most of this (35K SLOC) is in the client The UML/CS host site runs a (small) server-side program. Server and shared have only 1900 more lines of .java source code.. Server functions are rudimentary; with no aplication-specific security.) The browser's BDE2JAVA popup window asks me to choose local or remote and enter user name, passwd, host and port. ( Name and passwd accept any non-empty strings; host and port can remain empty.) When I checked Remote, the connection failed to open. When I checked Local, I entered name and passwd, clicked OK and the drawing canvas with bde's OOMenu for graphic editing at its left and the FILE popup menu button displayed above that quickly appeared. Hurray! 3. How to edit diagrams with bde2java:: ============================= These are only highlights. More complete info is in the BDE User Guide at http://www.cs.uml.edu/~lechner/06f522/COOL-BDE/BDEUserGuide2005/ (The BDE UG was written for bdeUnix, which has more features but a few limitations compared to bde2java. - E.g.no rounded rectangle nodeshape.) To begin editing, on the top-row FILE popup menu select Open or New File. Other top-row buttons (Edit, Options, Help) are not implemented for bde2java. 3.1 File Open works like most GUI's: ---------------------------------------- New File prompts for a File name then a Graph (diagram) name. Multiple diagrams can be created from the FILE popup's New Graph option (bdeUnix uses the OOMenu Graph Create operation below) Switching among diagrams is easy: The current diagram's unique identifier (pkey HGid) is displayed in a box above the OOMenu. Click it to open a popup list and select any of the available diagrams.in this file. [TBD:Implement the bdeUnix display of the entire HG-table with title etc., not just the object's pkey or oid.] An editing operation is selected on BDE's OOMenu at the left of the drawing canvas, by checking one radio button in each of the two left-side button arrays The upper array selects a particular class of drawable objects, and the lower one selects a particular editing operation to use. (I prefer these over a two-level popup menu to emphasize that class and method are 'peers'.as in the double-dispatch design pattern.) Each click on the canvas applies the pre-selected Create or other editing method to the clicked-on location or object of the pre-selected type. There is a Shape popup menu under the OOMenu to pre-select a Node shape. Link Create works by moving the mouse between two nodes: Start by button1 down inside the source node and end with button1-up inside the destination node. When a Node is moved, its links stay attached. 4. BDE drawing conventions for special diagram types: ==================================== 4.1 State models with self-loops ------------------------------------ State diagram nodes often need self-looping or cyclic links. To get one,draw links to and from an extra small circular Node.. Our bde2SM diagram to statemodel converter recognizes and removes this artifact. 4.2 Class diagrams with inheritance: --------------------------------------- UML class diagrams have one-to many inheritance relationships. To get one, add a bar-shaped Node separating the superclass Node from its subclass Nodes and connect them together via this barNode. Our bde2schema converter recognizes and removes this artifact. 4.3 Bendpoints for multi-segment links: --------------------------------------- Bendpoints can be added to a link and moved to route links around objects in their way. Bendpoints are represented as HP-rows in the diagram file.. 4.4 Multi-line Text in Nodes and Captions: ------------------------------------ Text Create may be applied to any Node or Caption [TBD: Link label text.] Text Create/Move/Delete is inadequate; Text in nodes ought to be parseable as formal specifications of class members (data and methods) and of source code (state action routines. [TBD: a better multi-line text editing approach in bdeUnix and bde2java. (Currently text is limited to file path names and HTML links.)] 5. Example of Block Diagram creation with BDE: =================================== I created an example with bde2java, saved on my PC and up-loaded it to UML./CS, where it is browsable as bde2javatest071208.bde at www.cs.uml.edu/~lechner/COOL-BDE/bde2java/bde2java04f/ (This diagram is missing the text it requires before input to GEN or LCP.) The BDE editing operations I used are described below: 5.1 File/New File: ------------------ I selected File/New File and entered filename "bde2java071208.bde" and a graph name "HG000001". Then I created 3 nodes (the first one took a few seconds, others were faster). and 2 pairs of links. 5.2 Caption Create/Move: ------------------------ I created 3 Captions and did Text Create on one. (It was buggy: 2 lines appeared, then all but the last one disappeared or were overwritten.) Caption Move worked OK. . 5.3 Text Create/Move: ---------------------- Text Move did not work well in Captions or Nodes. In Text Create within a Node, prior Caption Text appeared (bug) but I could erase it and enter e.g. "Node Circle Text" which apeared in the circular node. In fact more clicks duplicated this Node label many times. I could only use Text Deletefor lines that were positioned inside the circle. ( Node Move cannot be used to move the Node shape over the outlying text lines to be deleted because text moves along with the Node or Caption border.) Note that connecting the same pair of nodes twice by adding two links created a bendpoint at center of one link so they did not overlap. Moving a node will shrink/expand/move all its link segments proportionately so each link retains some semblance of its original shape. 5.4 FILE/New Graph (Graph Create): -------------------------------------- In bdeUnix, Graph Create adds more diagrams to the file, and Graph Select show the list of diagrams for selection. These are not implemented in bde2java. Instead, an uper left box has the Graph Title in it, and can show multiple diagram id numbers for selection. I used FILE/New Graph to name and create a 2nd diagram in this file. I can display either one by selecting its unique identifier from the list that pops up below the Graph Title 5.5 FILE/File Save[As]; ----------------------------- This saves a file which can be opened later for more editing. It prompts for a filename [.bde or .dat] and saves by default to C:\...\My Documents. 6. BDE File Format and Data Model: ======================= BDE's database schema is defined in file 94sbde_schema.sch[.txt] at http://www.cs.uml.edu/~lechner/06f522/COOL-BDE/bdeUG_2000/bdeschema/ This .schema file is parsed by GEN to provide source code.for managing diagram files. It is convertible to/from a BDE EERDiagram by bde2sch/sch2bde. Bde diagram files contain one relational table for each entity class. Tables have one row per object and can be version-controlled by RCS or CVS. Version control is appropriate for block diagrams that become precise models for programs, if and when augmented with software class methods (state action routines). These can be written in any programming language. that is linkable to C, C++ or Java. libraries. [TBD: Introduce a multi-site CVS repository for remote checkouts and commits of a shared BDE design file by a team of designers.] Every object has an immutable primary key in fixed position (column 1). This 'pkey' defines its type(subclass) and its object id in that class. Other component objects including asociative entities include foreign 'fkey' references. (To maintain referential integrity, these must have values that match some pkey.) Internally, pfkeys are compressed to integers. Each table has its own partition of GEN's current 32-bit int pkey range. The number of fkeys in an object implies its arity as a relation. E.g., in BDE, HLink is an associative entity class or relation of arity 2: HL has two fkey fields (HNid1 and HNid2) which means that HL defines a symmetric M to N binary relation between pairs of Node class objects.. The library produced by GEN provides efficient access to a memory-resident network-style database via an embedded pointer chain from each parent object to its components or assocoates.. 6.1 Example BDE diagram file: ------------------------------- The example below will help you visualize BDE's data model. This text file of type .bde was saved from bde2java and uploaded to http://www.cs.uml.edu/~lechner/06f522/bde2java2/bde2javatest071208.bde (BdeUnix uses type '.dat', but this conflicts with MicroSoft's default use.) This file specifies two diagrams as flat relational database tables of ASCII text that is human-readable to a much greater extent tham XML Relations are implemented by embedded primary and foreign keys. Pkeys are immutable and fkeys satisfy referential integrity constraints. HN[odes] and C[aption]G's belong to HG#1 or HG#2 (foreign keys). HN shape code letters C,R,E identify Circle, Rectangle, Ellipse shapes on HG#1, or N for the rounded-corner rectangles on HG#2. Node and Caption have center location height and width fields. HL[ink]s connect node pairs. HP (bendpoint) rows belong to a unique HL parent.and define an ordred sequence of link segments. [TBD: Add line width and pattern fields and Bendpt Restyle operations to HP as in bdeUnix.] . HA[ttribute]s contain text lines belong to Nodes. GX-rows contains text lines that belong toCaptions. All GX and HA rows below have the same 'Fixed' font and the same string content: "Node Circle Text". (Text house-keeping as well as editing is buggy and inadequate.) Comments are ignored. FSid and DAid are meaningless foreign keys at this time. // bde2javatest071208.bde: //----------------------------------------------------- HG000001 FS010000 HN010000 Guest 8Dec2007/056 8Dec2007/125 HG000001 HG000002 FS010000 HN010000 Guest 8Dec2007/120 8Dec2007/125 HG000002 HN000001 HG000001 FS010000 C 112.0 50.0 100.0 100.0 Fixed 0.0 0.0 0.0 0.0 HN000002 HG000001 FS010000 R 319.0 151.0 100.0 50.0 Fixed 0.0 0.0 0.0 0.0 HN000003 HG000001 FS010000 E 88.0 385.0 100.0 50.0 Fixed 0.0 0.0 0.0 0.0 HN000004 HG000002 FS010000 N 126.0 145.0 100.0 50.0 Fixed 0.0 0.0 0.0 0.0 HN000005 HG000002 FS010000 N 139.0 274.0 100.0 50.0 Fixed 0.0 0.0 0.0 0.0 HN000006 HG000002 FS010000 N 366.0 135.0 157.0 138.0 Fixed 0.0 0.0 0.0 0.0 HA000010 HN000001 DA010009 10.0 120.0 0 60.0 13.0 Fixed Node Circle Text HA000011 HN000001 DA010009 10.0 136.0 0 60.0 13.0 Fixed Node Circle Text HA000012 HN000001 DA010009 10.0 152.0 0 60.0 13.0 Fixed Node Circle Text HA000013 HN000001 DA010009 10.0 168.0 0 60.0 13.0 Fixed Node Circle Text HL000001 HN000001 HN000003 2 -1 HL000002 HN000003 HN000002 2 -1 HL000003 HN000002 HN000003 3 -1 HL000004 HN000003 HN000001 3 -1 HL000005 HN000004 HN000005 2 -1 HL000006 HN000005 HN000006 2 -1 HL000007 HN000006 HN000004 2 -1 HP000001 HL000001 0.30633932 -0.080737755 1 0 HP000002 HL000001 0.8387688 -0.0101380255 1 1 HP000003 HL000002 0.18666439 0.07987659 1 0 HP000004 HL000002 0.7721632 -0.0031881912 1 1 HP000005 HL000003 0.22070622 0.018135067 1 0 HP000006 HL000003 0.5242681 0.04047653 1 0 HP000007 HL000003 0.8161468 -0.028076764 1 1 HP000008 HL000004 0.15268107 -0.07878344 1 0 HP000009 HL000004 0.43935508 -0.16404055 1 0 HP000010 HL000004 0.69622576 -0.09258581 1 1 HP000011 HL000005 0.1933968 0.0039857235 1 0 HP000012 HL000005 0.8058299 0.0036882807 1 1 HP000013 HL000006 0.26124135 -0.00110345 1 0 HP000014 HL000006 0.7342068 -0.0015172488 1 1 HP000015 HL000007 0.28136423 0.0024360474 1 0 HP000016 HL000007 0.7196712 0.002984166 1 1 CG000001 HG000001 428.0 203.0 300.0 18.0 CG000002 HG000001 360.0 331.0 300.0 18.0 CG000003 HG000001 362.0 289.0 300.0 18.0 GX000009 CG000001 DA010009 0.0 Fixed 0.0 0.0 60.0 13.0 Node Circle Text GX000010 CG000001 DA010009 0.0 Fixed 0.0 0.0 60.0 13.0 Node Circle Text GX000011 CG000001 DA010009 0.0 Fixed 0.0 0.0 60.0 13.0 Node Circle Text GX000012 CG000001 DA010009 0.0 Fixed 0.0 0.0 60.0 13.0 Node Circle Text GX000013 CG000001 DA010009 0.0 Fixed 0.0 0.0 60.0 13.0 Node Circle Text GX000014 CG000001 DA010009 0.0 Fixed 0.0 0.0 60.0 13.0 Node Circle Text GX000015 CG000001 DA010009 0.0 Fixed 0.0 0.0 60.0 13.0 Node Circle Text GX000016 CG000001 DA010009 0.0 Fixed 0.0 0.0 60.0 13.0 Node Circle Text GX000017 CG000001 DA010009 0.0 Fixed 0.0 0.0 60.0 13.0 Node Circle Text //--------------------------- 6.2 Saving a Diagram File: ------------------------- Bde diagram files can be version-controlled by RCS or CVS. This is appropriate for blockdiagrams that can be precise models for program design specs when accompanied by [state] subclass methods written in your favorite programming language. FILE/Print as GIF and FILE/Print as PS both save one diagram per file with default names HG00000{1,2}{.ps,.gif}. [TBD: Implement the bdeunix technique: prefix the currently open file name as a prefix to these HGid's. E.g., save to bde2javatest071208HG00000{1,2}{.ps,.gif}. to identify the bde file from which they originated. Neither .gif (from a ps2gif converter) nor .ps is back-convertible (although our hand-coded .ps file could be reverse-engineeered). Adobe Acrobat Professional displays the .gif file promptly. It cannot display the .ps file. It tries to convert it to .pdf but aborts with this log indicating an endemic fontname problem: ------------ %%[ Error: Helvetica not found. Font cannot be embedded. ]%% %%[ Error: invalidfont; OffendingCommand: findfont ]%% Stack: /Font /Helvetica 12 %%[ Flushing: rest of job (to end-of-file) will be ignored ]%% %%[ Warning: PostScript error. No PDF file produced. ] %% ----------------- Appendix :A: Java Console Display of Editor Progress: ===================================== Java Console Log History: ------------------------------- Below are extracts from the java console log of my test run. (The Java console is a separate window useful for debugging.) This is provided in case you encounter similar problems at first. Some Java components might have to be downloaded from Sun. Down-loading the client .jar file takes a minute or so on a cable modem. =============================================== Java Plug-in 1.6.0_03 Using JRE version 1.6.0_03 Java HotSpot(TM) Client VM User home directory = C:\Documents and Settings\Robert Lechner network: Loading user-defined proxy configuration ... network: Done. network: Loading proxy configuration from Internet Explorer ... network: Done. network: Loading direct proxy configuration ... network: Done. network: Proxy Configuration: No proxy ` ---------------------------------------------------- c: clear console window f: finalize objects on finalization queue g: garbage collect h: display this help message l: dump classloader list m: print memory usage o: trigger logging p: reload proxy configuration q: hide console r: reload policy configuration s: dump system and deployment properties t: dump thread list v: dump thread stack x: clear classloader cache 0-5: set trace level to ---------------------------------------------------- liveconnect: Invoking JS method: document liveconnect: Invoking JS method: URL basic: Referencing classloader: sun.plugin.ClassLoaderInfo@18b8914, refcount=1 basic: Added progress listener: sun.plugin.util.GrayBoxPainter@d1e233 basic: Loading applet ... basic: Initializing applet ... basic: Starting applet ... basic: completed perf rollup network: Cache entry not found [url: http://www.cs.uml.edu/~lechner/COOL-BDE/bde2java/bde2java04f/kyang2/bde2java/Bde2JavaClient.jar, version: null] network: Connecting http://www.cs.uml.edu/~lechner/COOL-BDE/bde2java/bde2java04f/kyang2/bde2java/Bde2JavaClient.jar with proxy=DIRECT network: Downloading resource: http://www.cs.uml.edu/~lechner/COOL-BDE/bde2java/bde2java04f/kyang2/bde2java/Bde2JavaClient.jar Content-Length: 132,397 Content-Encoding: null network: Wrote URL http://www.cs.uml.edu/~lechner/COOL-BDE/bde2java/bde2java04f/kyang2/bde2java/Bde2JavaClient.jar to File C:\Documents and Settings\Robert Lechner\Application Data\Sun\Java\Deployment\cache\6.0\38\7e058ee6-3fa4425b-temp security: Loading Root CA certificates from C:\PROGRA~1\Java\JRE16~3.0_0\lib\security\cacerts . [more of the same]. . security: Saved certificates in Deployment session certificate store ================================== [My Java Console interpretation notes:]: ------------------------------------------- 'Run Application' opened a bde2java window but hung until I uncovered a virus-blocker window which asked me to allow remote nodes to talk to me. I approved this . but the connection aborted anyway. The log reported this with: ----------------------------------------------- basic: Stopping applet ... basic: Removed progress listener: sun.plugin.util.GrayBoxPainter@d1e233 basic: Finding information ... basic: Releasing classloader: sun.plugin.ClassLoaderInfo@18b8914, refcount=0 basic: Caching classloader: sun.plugin.ClassLoaderInfo@18b8914 basic: Current classloader cache size: 1 basic: Done ... basic: Joining applet thread ... basic: Destroying applet ... basic: Disposing applet ... basic: Joined applet thread ... java.net.MalformedURLException: invalid URL String: rmi://IBM PC:22/BDEServerImpl at java.rmi.Naming.parseURL(Unknown Source) . . [more of the same] . at java.awt.EventDispatchThread.run(Unknown Source) Caused by: java.net.URISyntaxException: Illegal character in authority at index 6: rmi://IBM PC:22/BDEServerImpl at java.net.URI$Parser.fail(Unknown Source) at java.net.URI$Parser.parseAuthority(Unknown Source) at java.net.URI$Parser.parseHierarchical(Unknown Source) at java.net.URI$Parser.parse(Unknown Source) at java.net.URI.(Unknown Source) at java.rmi.Naming.intParseURL(Unknown Source) ... 32 more java.lang.Exception: Error While Connecting Server at bde2java.client.Bde2JavaRemoteDataManager.(Bde2JavaRemoteDataManager.java:25) . . [more of the same] . at java.awt.EventDispatchThread.run(Unknown Source) basic: Quiting applet ... liveconnect: Invoking JS method: document liveconnect: Invoking JS method: URL basic: Referencing classloader: sun.plugin.ClassLoaderInfo@18b8914, refcount=1 basic: Added progress listener: sun.plugin.util.GrayBoxPainter@c12474 basic: Loading applet ... basic: Initializing applet ... basic: Starting applet ... basic: completed perf rollup -----------------------------------------------------