UCOSPLogMarcdeNiverville

Marc de Niverville edited this page Dec 6, 2016 · 18 revisions
Clone this wiki locally

Each UCOSP participant is asked to log all the steps they take as they make progress through the semester. This includes difficulties they faced (getting set up, understanding how to model in Umple, using UmpleOnline, code that is difficult to figure out, and development tools that are hard to figure out, or don't seem to work properly). The more log entries added the more we can better get a grip on the usability issues with Umple, and the more we can help future new contributors come up to speed.

Please record entries in reverse chronological order

Log Entries

Date

December 6, 2016

It has been a big push these last seven days to get a working and significant increment of new features that would constitute a final pull request. Making the new code generator was easier than I thought it would be. I soon wrote a little shell script that strung together the commands to rebuild Umple, make a new umplesync.jar, and output the new JSON representation of some class + state machine model of interest.

I made steady progress working through displaying simple, or single-level state machines. It was at this time that I did most of the work elaborating the new plug-in for JointJS, working out how to parse, instantiate, and display the diagram elements. The parsing code was also refactored to make more of a separation between the view management and the parsing, since it is now managing multiple types of diagrams and must be able to switch between those types without being triggered by the response from a new AJAX request.

I added a button to the class diagram elements, to be revealed and be functional only for those classes that also have state machines. Initially, I tried to create the buttons as new diagram objects. JointJS offers an embed() function that establishes a parent-child relationship between nodes; this still allows a lot more freedom for the user to manipulate the child object, which is not appropriate behaviour for a fixed icon. The solution was to add an element to the SVG markup that defines the class diagram object. The state machine diagrams also needed a 'back' button, to allow the user to return to the class diagram. This was most easily implemented as a new diagram object, as it would be included in the auto-layout procedure and be placed close to the start pseudo-state node. To make the buttons work, I added an event handler to the overall diagram view, and a function that sorts out the event circumstances to determine which action to take.

However, things got more interesting as I turned to extend the code to render nested state machines. Revising the generator was still fairly straightforward. Since the Umple meta-model has a regular and recursive structure for the nested state machines, my previous work was readily adaptable to getting called recursively. The single biggest challenge was with the auto-layout mechanism in JointJS.

The layout mechanism is designed to work with graphs: nodes and edges. Each state is a node, each transition is an edge, and each state machine a graph of states and transitions. The wrinkle is that with nested state machines, we want to encapsulate sub-machines within their parent states. Ideally, we would be able to auto-layout a forest of lowest-level nested state machines, encapsulate them within their parents, then perform another cycle of auto-layout on their parents, working our way up the hierarchy to complete the diagram. Until now, I have not found a way to accomplish this; the auto-layout process breaks down at the level of the first parents, separating them from their children.

December 1, 2016

There is just one week left to go in the term! In some moments, the features that I have committed to implement seem larger than can be done in the time that is left. It is that the scope of the work touches on so many different aspects. However, today's progress gives me hope that I can get this done in time.

The JsonMixedGenerator has been partially re-written to produce JSON data that is directly instantiable into a state machine diagram. At this point, it works with single-level state machines.

I have begun the new plug-in for the JointJS library to display state machine diagrams that conform better to the UML specification. There is enough to instantiate all of the data produced by the JsonMixedGenerator: start pseudo-state, regular states, final state, transitions. The transition labels show the event name, guard, and action. The states show entry and exit actions, and internal transitions. (Yes, the Microwave Oven example has one.) The states are rounded rectangles with lines separating the different types of data. With this in place, only a small amount of glue code is required to feed the JSON to the new plug-in.

The last challenge tackled today was to determine how to get the auto-layout working. Only one line of code is required to trigger an auto-layout operation; the difficulty I faced was figuring out how to load the two additional dependencies. Now the script will perform the auto-layout. The resulting diagram for the Booking example looks perfect. However, the results with the Microwave Oven are not so impressive, and this is due to the great number of transitions involved. There are overlapping transitions, and some transitions overlapping states. I have already found a way to sort out overlapping connections in the class diagram, so I should be able to correct them here too.

November 28, 2016

For the last week and a half, I have been working on implementing the creation of state machine diagrams with the JointJS library. This has required doing a deep dive into a number of topics that are unfamiliar to me:

  • the Umple model for state machines
  • the UML standard for state machine diagrams
  • writing Umple code to parse the Umple model and generate JSON data

In order to implement with JointJS, I will also need to get even more familiar with the library, as the JointJS template for state machines doesn't follow the UML standard and is too simplistic to illustrate all that we want to show. Given that Umple has no current structured JSON format for generating state machine data, and that there is no complete JointJS format for our diagramming requirements, there doesn't exist a specification for structured JSON data for the state machines. While my work has begun on the Umple side, creating a new generator to parse the combined class and state machine model, I have realized that I must be a little cautious and not get too far with parsing the Umple model without seeing how I can parse the JSON in the browser. My strategy is to develop the specification from both ends. As of this evening, the new JSON generator produces enough data to draw a state machine with entry and exit actions, and transitions with guards and actions. The next step is to work on the browser side to draw the full diagram.

November 7, 2016

I have continued work on elaborating the links between classes. There are some link types that require more control over the path shape, such as associations that connect a class to itself, and generalizations which are shown as conforming to a rectilinear grid. In both cases, this has been accomplished by specifying the location for some vertices on the path depicting the link.
There is also the odd situation where there are multiple associations between the same two classes. The initial result is of overlapping associations, so that the bottom ones are being hidden. This remains to be corrected.

The next increment of work is to make the JointJS diagram responsive to the user's selection of display choices, whether or not to display class attributes and methods. Implementing this will require creating methods to resize the cell that is the abstract view for each class, as well as the SVG rectangles that constitute the concrete view.
There is currently a bug that is apparent when a class's methods are displayed: the displayed class is not properly sized to hold all of the additional text, so it runs outside of the box. I am thinking now that the means to resize these entities will address the feature and the bug. So far, my investigation shows that the JointJS library does attempt to adjust the size of all of the constituent rectangles as part of the object instantiation process. It calculates a containing rectangle's height by counting the number of lines of text it must contain, and adds some padding. The resulting SVG rectangles all bear the correct dimensions from these calculations. However, it looks like the SVG group that contains the rectangles is scaled disproportionally in order to make the rectangles fit to the original inputted dimensions. The original dimensions received from the server do not appear to account for display of the methods; in fact, this would conform to the default display selection.

November 1, 2016

The pull request was merged over the week-end, after I addressed a number of issues. This was my first exposure to block-by-block code review, with Github linking a code snippet with each of the reviewer's comments. I was then able to address each in turn and write back some response. It was immediately obvious that this is a much more effective way to conduct a discussion about code than anything I've been exposed to before.

I received some helpful comments from Tim and Vahdat, and have been working to make a slew of enhancements to the rendering of the class diagram. As I get more familiar with the JointJS library, I am discovering the easy ways to get things done. For example, adding the role and multiplicity to associations was a simple task of adding labels with text, position, and other formatting parameters:

labels: [{ position: .5, attrs: { text: { text: assoc_name || '', 'font-size': '8pt'} } },
{ position: .05, attrs: { text: { text: UMLassoc.multiplicityOne || '', 'font-size': '8pt' }, rect: { 'fill-opacity': '0.6'} } },
{ position: .95, attrs: { text: { text: UMLassoc.multiplicityTwo || '', 'font-size': '8pt'}, rect: { 'fill-opacity': '0.6'} } }],

In addition to the already established label attribute, the Link prototype on which Associations are based already has methods for changing or resetting the formatting.

October 27, 2016

Today's focus of work was in implementing a proper diagram zoom feature for the JointJS class diagram. There were two questions to resolve. The first was about which view element(s) should trigger the mouse wheel event. The JointJS Paper prototype provides a number of events already: blank:mousewheel is triggered when the mouse wheel is turned while the cursor is above a blank area in the canvas, while cell:mousewheel is triggered when the mouse wheel is turned while the cursor is above a call. So the pair cover the whole of the rendered area. Unfortunately, the data returned about mouse wheel action is very different. blank:mousewheel returns a mouse wheel delta of 1 or -1. However, cell:mousewheel returns a real-numbered mouse wheel delta in the positive range only, i.e. with the cursor hovering above a cell, there is no way to determine whether the user wants to zoom in or out. Eventually, I settled on setting the mouse wheel event handler on the umpleCanvas div.

The second question was about how to create the zoom effect. The JointJS Paper does provide a scale method, so I first attempted to use that. Since the Paper has a set size, zooming in on a large model might put the model extents outside of the canvas boundaries. So the user would not be able to scroll to see the parts of the model outside the boundaries. There may yet be an algorithm to deal with this. However, the method that I have implemented is to change the size of the paper during the zoom, and to scale the contents to fit it. I am interested in getting feedback on the results, to better understand its shortcomings.

There is now a pull request to pull the work so far into the master branch.

October 24, 2016

The next increment of work performed today was to take what I had developed in my experimentation and link it to umpleonline. This consisted of adding a few lines of code to instantiate the joint object (from JointJS library) and to call the little parser/model instantiator that I had written. Now, any class model on the umpleonline site can be viewed with (very basic) JointJS formatting. Associations and generalizations are not yet being drawn, and most of the other UI elements have not been implemented.

EDIT: the question of how to add the association links was nagging me... it turns out that it is very easy to add associations once the classes have been instantiated.

October 20, 2016

I spent some time today going through some of the relevant tutorial examples for JointJS, and experimented with instantiating some Umple objects with JointJS. Once I had formed the expectation that the JointJS classes were probably decent abstractions of what a UML class should be, I found that there is a correspondence between the umpleClasses (JSON) object properties and the properties of joint.shapes.uml.Class. However, the representation of attributes and methods are probably too simplified to be useful for anything other than display; the attribute or method modifier, name, and (return) type, must all be represented as a single String. Once I get a better grip on how the diagram cells are created and maintained, I may attempt to sub-class the joint.shapes.uml.Class to add the ability to hold the original attribute and method objects in their respective cells.

October 17, 2016

After last week's call, I took a closer look at the AJAX requests and responses that were produced while editing the model in Editable Class mode. I found that the server response is a JSON object that represents the UML model.

Building on yesterday's work, I have identified where the AJAX request is made (with Action.updateUmpleDiagramForce() method) and how the server response is handled (with Action.updateUmpleDiagramCallback()). Both methods have been modified to make and process the identical request, but while the JointJS class view is selected.

There is now a code block established that will receive the the server's response, while the JointJS class view is selected, and in which I will add the method calls to instantiate the JointJS model and diagram. The next step is to learn the details of the JointJS API and how to use the UML plug-in.

October 16, 2016

Today's work accomplished the addition of a UI element for the user to select the JointJS library for displaying the class diagram. There is now a radio button along with the other radio buttons selecting diagram types. There is also a tool-tip that appears, just as the other radio button options have. I have also assigned the [ctrl+j] keyboard shortcut to select the JointJS option.

My process was to duplicate the html pattern for the radio button, then methodically elaborate the scripts that use the new element id's, names, and values. This has provided a different, and helpful, perspective for tracing through the various affected JavaScript files (umple_action.js, umple_page.js, umple_restore.js).

One piece of magic I haven't yet figured out is how a click on a radio button, with id such as labelShowEditableClassDiagram gets turned into an event with name ShowEditableClassDiagram.

October 10, 2016

In preparation for tomorrow's conference call, and to support the quick selection of a 3rd party JavaScript library to use to draw diagrams on the umpleonline web site, I have been doing a lot of reviewing of the candidate libraries. Where possible, I visited the project repositories, to look for evidence of recent activity, to assess the helpfulness of the documentation, and to get a sense of the various APIs. For the review of the APIs, I was looking for the level of abstraction offered to manipulate the diagram or drawn elements, and to see what features of a user interface were implemented.

October 6, 2016

Now that I have assigned myself issue #600 as my term project, I need to come to understand it well. I have been doing the following:

  • spending a fair bit of time working with the umpleonline site and demos, inspecting the page html and elements
  • inspecting the site's scripts, both for server and client
  • reading Internet articles about JavaScript diagramming libraries and checking out their site pages and demos
  • discussing the project with Vahdat
  • added a comment to the issue page to document our thoughts about the project and ratings of the best available libraries

September 24, 2016

Working through the resolution of issue #853:

  • completed tracing the code execution, and became more proficient with use of the Eclipse debugger and variable inspector; along the way, looked at a good number of generated code files especially focusing on UmpleInternalParser.java
  • began to grasp the relationship between umple code for the Umple application, and the generated (and auto-generated) code
  • discovered a few wrinkles in creating test cases and destroying the generated files
  • after completing the full build to confirm correct performance of the changes, started a local server for umpleonline to interactively check the fix with other cases
  • added an explanatory comment to the issue and wrote a pull request to pull in the branch with the code changes

September 20, 2016

Working through establishing the development environment:

  • performed a full build on the command-line last week, but did not search through all of the messages to look for "failed" messages
  • today imported the project into Eclipse, encountered a hiccup with Eclipse selecting JRE 1.6 instead of 1.8, so that many errors were reported throughout the generated JAVA code
  • after fixing the JRE choice and performing a Project->Clean, all reported JAVA errors disappeared; then attempted to run the full suite of unit tests which resulted in approx. 4,000 errors
  • repeated the full build with ant -Dmyenv=local -Donline=false; no "failed" messages were apparent, through there were a few warnings generated from the code-base and from the existence of two instances of ant on my system path
  • restarted Eclipse, performed another Project->Clean; ran unit tests now, resulting in 0 errors and failures, with 154 tests skipped