Chapter III AN END TO END EXAMPLE

Transcription

1 44 Chapter III AN END TO END EXAMPLE Chapter Summary All of the stages of using the Ultraman tool and run-time to create a new view from an existing view are explained in this chapter by working through a single example. A summary of these steps is: 1. Preparation: One must identify the portions of the input interface to be transformed, where the results should be placed, and what type of computation should be use to do the transformation. 2. Using the tool: The new view s designer must express to the Ultraman tool the pattern(s) to match, what user-written transformation actions to call with matches that are found, and what parameters (derived from the found matches) are to be passed to the user s transformation actions. 3. Writing the transformation actions: A user action must transform the parameters passed (see step 2) into output interactors, structured as a tree of nodes. These resulting nodes are attached to shadow objects, which perform Ultraman s state preservation functions. The shadow object s must be initialized by user code, generally this is done at the time the object that the shadow object represents is initialized. 4. Updating the system: In the current implementation, Ultraman s run-time must be informed each time an event is handled by the user s application. Each time Ultraman is notified, it recalculates the derived

2 45 interface(s) from the source interface (preserving or reclaiming as much of the previously derived interface as possible). Introduction Through the course of this chapter we will explore how to use the Ultraman tool & run-time to create a new view in a fictional organizational chart application. In this scenario, we will assume that we have already constructed an organizational chart editor and the organization chart can be modified using a traditional browsing view. This standard view shows a collection of nodes organized into a tree; this shows who reports to whom in an organization. This view is what is normally referred to when one mentions an organizational chart. This standard view can be directly manipulated: Nodes and thus people and their subordinates can be dragged in the view to change its structure. Dropping a node on another node indicates that the dropped node should be considered a direct subordinate of the node dropped on. A mock up of a screen shot of our example application is seen in Figure 3-1. FIGURE 3-1 Mock Up Of The Organizational Chart Application By using Ultraman, we seek to build a new view which creates a departmental listing. For the purposes of this discussion, a departmental listing contains the names of a group of people who are contained in a large-granularity organization within a company. Example departments might be engineering, operations, or marketing. In the example, our departmental listings are a list of names of people which are

3 46 sorted on the primary key of the department they work in, the secondary key of their last name, and the tertiary key of their first name. An example departmental listing might look something like this: FIGURE 3-2 Example Departmental Listing Preparation Before starting out to use the Ultraman tool and run-time, we must make three important decisions about our new view. The decisions are, in summary: 1. Determine the important structural features of the original view in our example for this chapter, the original view is the standard organizational chart view 2. Decide the structure of the top of the generated interface for this example, this is the departmental listing view 3. Decide whether the computation which converts the original view to the generated view is of a local or global nature

4 47 Visual Presentation FIGURE 3-3 Structure Of UI Tree In Organizational Chart Application The first of these decisions is important in that it will dictate what the patterns are that Ultraman searches for at run-time. The second of the decisions is primarily an optimization, but is used often because the user interface tree of an program almost always has several nodes at or near the top of its tree which are unchanging. The third decision is primarily one of programming convenience: local computations allow the programmer to work with a simpler API but have less computing power. Determining The Important Structural Features For this example, we will assume that the tree of interactors that form the original, standard view are organized as in Figure 3-3, Structure Of UI Tree In Organizational Chart Application, on page 47. For our purposes the only important structural feature of this tree is at the bottom of right hand side of the tree, a repeated pattern. Each use of this pattern indicates that an entry in the organizational chart is visible to the user. We are assuming that the OrgEdge node is an interactor which displays an (incoming) edge on the screen so that a superior node in the chart is connected to its subordinate. We further assume that OrgEdge might contain semantic pieces of data about the type of connection between this superior subordinate pair.

5 48 FIGURE 3-4 Pattern Structure So our new departmental view will be computed from the structure shown in Figure 3-4, Pattern Structure which has three constituent nodes. The reader may wonder Why not just use the one node that has the data of interest the TextBox? The RoundRect and the OrgEdge are probably only for display purposes. The reason to use the entire structure is to insure we only select TextBoxes which are the ones of interest. We could achieve the same end by having a pattern which contained only a TextBox and placing predicates on the TextBox in the pattern, but it seems more clear to proceed with the slightly larger pattern and no predicate. Deciding The Structure Of The Top Of The Generated Interface For the purpose of simplicity, we will assume that the top of the generated interface has only three nodes as seen in Figure 3-5. These three nodes are there to allow the user to see the interface on the screen (the Frame object), have a scrolling view onto the potentially large number of interactors (the Scroller object), and display the objects neatly in a column (the Column object).

6 49 FIGURE 3-5 Structure At The Top Of The Generated Interface Deciding If The Computations Are Of A Local Or Global Nature Note to committee: Due to some suggestions on previous drafts, this section may be removed later in favor of a new code generation approach which unifies aggregators and transformation functions. This decision of whether or not the transformation from the original interface to the new, generated interface is a local or global one is primarily one that can be made on the basis of programming convenience. Ultraman provides two different, but related mechanisms for doing computations. These two mechanisms are transformation actions, which correspond to local computations, and aggregators, which correspond to global computations. As one would expect, aggregators being a global computation can always subsume transformation actions, a local computation; as we will see later, this is also true formally. The reason both mechanisms are provided is that aggregators require the end-programmer to conform to a slightly more complex API. The reader should keep in mind that at this point only the decision needs to be made about the type of computation, we will make Ultraman aware of our decision later. A transformation action is piece of code written by the user for perform the conversion of patterns into output. Generally speaking, the code is a user-defined, static Java method. When a pattern of interest is found by Ultraman, the transformation action, if any, for that pattern is called and the transformation accomplished. For any call made into the user s transformation action, the Ultraman run-time expects a function signature of this form: static void myfunc(object obj); The void return type indicates that transformation functions are usually called for effect, or, in other words, to put user interface object into the output tree. (A design alternative that was considered was for the transformation action to return the parts of the output tree and have the programmer specify where Ultraman should place these returned values. This seemed to have a substantial limiting effect on the flexibility of the

7 50 end-programmer to choose where to put the nodes in the generated output. For example, many types of conditional placements become much more complex to express.) The parameter to the user s transformation action is of type Object. The origin of this value is explained more thoroughly in the section The Tool Proper on page 52. In summary, this value can be thought of as the distilled version of the contents of the pattern at run-time; the object passed represents the actual values matched. The type of Object was chosen to allow any type of object to be passed as a parameter. An aggregator requires that the end-programmer follow a slightly more complex API. For the purposes of exposition, we are going to assume that we are interested in an aggregator called count which counts up the total number of instances of some pattern that are found. This highlights the difference between transformation actions and aggregators: a transformation action would be appropriate if you needed to perform a computation on each pattern, an aggregator counts up the total number of patterns. For an aggregator referred to as count Ultraman will assume the existence of three static, Java functions. They have the following signatures: static void countinit(); static void count(object obj); static void countfinish(); The second of these functions will be called in a way that is exactly the same as our above description of a transformation action so it is now clear that aggregators are a proper superset of transformation actions. The first and last of these functions are called by Ultraman s run-time at the beginning and end of the overall transformation respectively. These functions are not called on each match of a pattern, but before and after any patterns are found. The calls to the init function and the finish function give the user code an opportunity to prepare and complete its global computation respectively. In an example like counting, the init function would contain code to initialize a counter to zero and the finish function would actually add nodes to the output tree based on the count actually found during the transformation sequence. For simplicity in this example problem, we will choose to use a transformation action, and we will name this transformation action xform. As explained above, this function gets called every time a pattern of interest such as the one in Figure 3-4 is found, and its job is to convert patterns into interactors for the generated interface. The full text of the function xform appears below in the section Transformation Actions And Shadow Objects on page 56.

8 51 Using The Ultraman Tool Now that our preliminary decisions have been made, we can actually use the Ultraman tool to hook up the pattern matching engine to our code. This is done using three distinct steps: 1. Inform Ultraman about the parts of our code of interest 2. Use the tool to create pattern(s) 3. Use the tool to create parameters for our code to work with Declaring Transformation Action As we explained above, we are using a transformation action named xform which performs the work of converting our found patterns into items for the departmental list. At this point, we need to make Ultraman s tool aware of the name of our function so that code generated by Ultraman can correctly call our code. We do this by creating a Java class which has in its source code the name of our transformation action. This requires just cutting and pasting from an existing piece of code in our case. Ultraman provides a base class which encapsulates almost all the information needed by the tool about a transformation action; the only thing the user supplies is the name of the method in their code to call, i.e. xform, as a Java String. (To be more exact, the user supplies both a String which is the name of their transformation action s function and a String which is the text to be displayed in the tool s user interface. However, these are almost always the same, so this distinction is of little importance.) The code containing this information is compiled and placed in a well-known directory so Ultraman will find it at the time the tool starts up. When the code is found by the tool, the name of the user s function is known by the system and the transformation action can then be used with the tool.

9 52 FIGURE 3-6 Screen Dump Of The Ultraman Tool The Tool Proper When we start the tool, we will note that our newly declared transformation action, xform, is visible in the list of transformation actions in the upper right portion of the GUI, shown in Figure 3-6. By selecting the radio button labelled with our code s name, we have told Ultraman to connect this pattern to this user specified code. This screen shot also shows the structure from Figure 3-4 in the top, central portion of the window. By putting the structure from Figure 3-4 in this portion of the interface, we have expressed to the tool and run-time that this is the pattern we are interested in matching. Editing this structure can be accomplished by activating a pop-up menu that is found on each node on the structure; nodes can be

10 53 renamed by double-clicking on them and editing their text. (We have used unqualified typenames as the types of each node in the structure above for clarity. Most uses of Ultraman would require the fully qualified Java-style nomenclature.) The center, horizontal strip of the interface is the region for putting aggregators. Aggregators are functions which compute a value of the entire input interface tree, not of each pattern matched. We have not selected any aggregators, so Ultraman will not attempt to do any aggregation for this particular pattern. In the current implementation, the user can have a transformation action, an aggregator, both, or neither as the connection to a particular pattern. As explained before, aggregator differs from a transformation action in that an aggregator can compute a function such as How many people have Bob as their immediate superior? instead of Transform each of Bob s subordinates into a node in the new view. The latter is more typical of a transformation action. More information about aggregators and their relationship to transformation actions can be found in Deciding If The Computations Are Of A Local Or Global Nature on page 49. The final piece of our puzzle is the program code at the bottom of Figure 3-6. This code is allowed to be any legal Java program segment. It will be copied into the resulting run-time as the body of a Java method and thus many contain any legal Java statements or declarations. Before we go too far, let us return for a moment to the structure pictured at the top of the interface in the screen dump. Each node as an uppercase letter associated with it the letter before the colon in each node shown in Figure 3-6. This letter is the label for each node. When a pattern is found at run-time by Ultraman, each matched node is bound to a variable which has the same name as the corresponding label shown in the screen dump above. This process of binding matched values to names allows the end-programmer to effectively address the values of nodes found in the input. The purpose of this program fragment at the bottom of the screen dump is to supply the parameter that is needed by a transformation action or the normal part of an aggregator (See Deciding If The Computations Are Of A Local Or Global Nature on page 49). As explained previously, a transformation action takes one parameter of type Object. We are going to overload that one parameter with three parameters by using the Java type Vector an object which holds any number of other objects inside it. We will pass three parameters inside the Vector which will be unpacked in the body of our transformation action, xform. In order, the contents of the Vector will be a String with the department name, a String with the employee s last name, and a String with the employee s first name. In general this program fragment will compute something that approximates the return value of this pattern. This return value is passed to transformation actions and aggregators as the distilled version of the pattern that was found.

11 54 To return the program fragment in the bottom section of Figure 3-6, we can see that the first substantive action this code does is to extract the found interactors from the source tree and cast them to the proper type. These nodes are inside objects which are the actual tokens the lexer operates on. (The design choice to allow programmers to see tokens, which themselves contain useful information to some users, is a trade-off against the inconvenience of having to retrieve the interactors from inside tokens when they are needed. More details about the lexer subsystem of Ultramaan can be found in subsequent chapters.) The found interactors are interrogated for useful information which is then stuffed into a newly created Vector, in the middle section of the code, and this Vector is returned. This Vector will become the return value of this pattern. Although any computation could be done in this section, most commonly this code is used to distill the pattern down to the important essence of the data in the pattern. It is this essence that is going to be needed to compute the transformation action. The value returned (v in our example code) is then passed to the designated transformation action (xform) for the actual transformation. The passing of v to xform is done automatically by the Ultraman infrastructure. Slightly more precisely speaking, the Ultraman infrastructure takes whatever value is returned by the program fragment and passes to any selected transformation action. The separation of concerns makes it easier to connect different types of patterns to the same transformation action as well as greatly simplifying the transformation action s code since it need not be concerned with what patterns are, how Ultraman works, nodes or token types, etc. A summary of the sequence of events involved in a transformation action and the pieces of code used can be seen below: 1. Ultraman discovers a pattern of interest in the original interface, such as the pattern shown in Figure 3-4, Pattern Structure, on page 48, 2. Code snippet called to convert pattern into parameter, as seen in at the bottom of Figure 3-6, Screen Dump Of The Ultraman Tool, on page Return result of the code snippet passed to transformation action, such as xform whose code can be seen on page 57

12 55 FIGURE 3-7 Screen Dump Of The Ultraman Code Generation Dialog Generating Code Once the patterns and the connection to application code is completed, the tool can be told to generate code. At code generation-time, there are several options that can control how the generated code ends up fitting into the final application. All of these options can be see in Figure 3-7. Probably the most important of these options is the Code Gen Prefix which is the string that is prepended onto the names of the generated parser and lexer. (This name is analogous to the use of yy in the lex and yacc tools on unix systems.) The Package Prefix field and the Directory field allows the user to declare the Java package and directory of that package that the user would like the generated parser and lexer emitted into, respectively. The final two fields are the Pre-Parse Hook and the Post-Parse Hook which are called before and after the parse respectively. The value of these fields above is empty, so no user defined code is called either before or after the entire parse; if there were values in these fields, they would be the name of user-written functions. By using these fields the user can perform global initialization and shutdown. The sanity checking checkbox is primarily of interest to persons doing development of Ultraman itself; most users simply leave this box checked since the default insures that Ultraman performs self-checking as it runs. The bottom section of this dialog box is another free form area of Java code. This section is normally used to insert import statements so that, at a later point, the Java compiler used to compile the Ultraman-generated code will not generate errors due to unknown types. The code generated by Ultraman is not Java code itself, but an input file to the LL(k) parser and lexer generator ANTLR [ref here]. Before the code can be compiled and linked together with user code, ANTLR has to be run over the input file, whose name is pre.g for a code gen prefix of pre. Several files are generated by ANTLR, but the only ones of importance here are again for a code generation prefix of pre

13 56 prelexer.java and preparser.java. These files, along with parts of the Ultraman run-time, contain all the code for matching the patterns in an input user interface tree and dispatching the matched patterns to user code. Writing A Transformation Action When one begins to write a transformation action, the primary things to keep in mind are, What transformation am I trying to accomplish? and Where do the resulting, output nodes belong in the transformed tree? In our example, the answer to the first question is that we need to convert a Vector of three strings into a line of text (Ala Figure 3-2) in the correct ordinal position in a Column so as to keep the table sorted. We are not going to consider how to line up the employee names and the department names into columns, as shown in Figure 3-2, but as we will see later this could be easily accomplished. The answer to the second question is a little more complex, and will be addressed in what follows. Initialization-Time As will be explained more fully in future chapters, one of the primary technologies brought forward by Ultraman is the ability to preserve state in transformed interfaces. To exploit this ability, the transformation action writer must add a small amount of code to the initialization sequence of his or her program. This line of code declares a shadow object which is a global variable we will call shadobj and attaches it to a point in the output tree immediately above where we are going to be placing the transformed labels. Recall that earlier ( Preparation on page 46) we decided on the structure of the top of the output tree; we are now attaching a shadow object at the leaf of that tree. For our example, the only a single line of code would be added to the initialization of the program and the line of code would look like this: shadobj = new ShadowObject(theColumn); Throughout this discussion we will describe all of the generated nodes of the transformation as being placed into or made children of shadobj. In every case, we mean that we are placing the object inside the shadow object so that it can act as a proxy for the column object. Since the API of the shadow object is the same as the column, it is a simple matter for the end-programmer to simply use the shadow object instead of the column. Thus, the answer to our second question posed above, Where are the result nodes added? is simply, They are added to the shadow object. Transformation Actions And Shadow Objects Returning to our discussion of the writing of our transformation action, our job as the writer of the transformation action is clear: Take the Vector of values passed to us by Ultraman s infrastructure (the same

14 57 one we computed previously, See The Tool Proper on page 52) and convert it interactive objects suitable for display in the departmental listing. The objects should be attached to the shadow object, shadobj, so they can be affected by Ultraman s state preservation infrastructure. Label left, right; Row final; Component comp; // unpack arguments String dpt=(string)v.elementat(0); String lname=(string)v.elementat(1); String fname=(string)v.elementat(2); // create a label with the person s name left=new Label(lName +, + fname); // label with the department right=new Label(dpt); // make a row with the name and the department // (using a row allows us more flexibility later if we need // to line up the columns as in Figure 3-2) final=new Row(); final.add(left); final.add(right); // find predecessor of this node for use in insertion sort comp=findpredecessor(dpt, lname, fname); // insert our row after predecessor shadobj.add(comp,final); The comments in the above code segment explain how the code works, but a couple of important, higher level issues should be noted. First, the feel of this code is very straightforward: Take the arguments provided, do a small computation, and attach the result to the output tree (more precisely, attach the results the shadow object representing relevant piece of the output tree). This code is quite isolated from both the pattern matching system of Ultraman and the state preservation system; neither of these Ultraman-related issues are really important to this code. Second, this code is quite specific to the particular semantics of this application. Even ignoring the extraction of the parameters from the Vector, determining where to insert this node into the list of people in a department does not seem like a function Ultraman could or should be providing. As we have phrased our example here, the departmental listing created by this code would be noninteractive or output only. We could easily change the code above to output an interactor, like a button, which has some type of input behavior. None of the code generated by the Ultraman tool or any of the input needed by the tool would need to be changed. The only necessary additions would be the user code to perform the input behavior of the button. Further, as our example stands now with its column of rows each row will have its state preserved by the shadow object. This might become much more significant if we changed our transformation action to output a column of radio buttons which have a notion of a currently

15 58 selected item, or some other interactive object which allows its text to be selected for the purposes of copying to the clipboard (even our labels might allow this). Putting It All Together Note to the committee: At Scott s suggestion, I m planning to make a small code generation change which will simplify this section somewhat by avoiding the need for the exception handler below. The only remaining question to be answered by how our example should work is how to inform Ultraman when to do its job. In a perfect world, we would like Ultraman to run after each and every user event is dispatched and to do its work without end-programmer intervention. By running after each event, Ultraman could be sure that interfaces which are being generated by its transformation process are always in synch with their source. However, at the current time our implementation does not have any way to become aware of when each event is handled by the application. Thus, our application must provide some help to Ultraman to inform of it of when to perform its work. (JavaSoft has announced and published specs on an API which would allow monitoring of each event that the system processes, but this API is not yet available. Such an API would avoid the need for the help that Ultraman currently receives from the running application.) Under these circumstances, our application must tell Ultraman when to run and our application should do this at each time that an event is handled. More precisely, the application should notify Ultraman each time an event is handled which could affect the state of the generated interface. It stretches credulity to think that an application programmer could make this calculation, so informing Ultraman after each event is processed is the way we expect to proceed. The code necessary to tell Ultraman assuming you use a prefix of Org at code generation-time (See Generating Code on page 55) to run is as follows: try { // mainframe below is your source interface (the input to Ultraman) OrgParser parser=new OrgParser(new OrgLexer(mainFrame)); parser.top(); } catch (antlr.parserexception e) { System.out.println( PARSER PROBLEM: + e.getmessage()); System.exit(1); }

16 59 In simple terms, all that is necessary to do is to instantiate the parser/lexer pair which was generated by Ultraman and cause it to start parsing at the top (start) symbol. All of the machinery of the Ultraman pattern matcher, user code dispatcher, and state preservation system is handled by this routine. The reader may be wondering about the exception handler for antlr.parserexception. If Ultraman is functioning properly, this should never occur. This exception handler is not of interest, and should never be executed, during a normal execution of an Ultraman program. If this were to execute, it would be due to a bug in the code generation phase of Ultraman. The only other time that an exception might be thrown in the body of the code above is when user defined code throws an exception. Obviously, the end-programmer is responsible for catching exceptions he or she defines and throws. The primary utility of an end-programmer throwing an exception is to indicate that a point in the transformation process was reached where application semantics mandated that the transformation be stopped completely or stopped and restarted at a different location in the input. To resume processing at a different point in the input, the code above would be repeated but with a different interactor substituted for mainframe. The Parts Of An Application At this point, we will attempt to summarize where the various parts of an Ultraman application reside, who generates them, and what their various interactions are. This can be very useful in understanding the overall structure of an application which uses Ultraman. Figure 3-8 shows the major parts of our example (and representative) Ultraman application, after the Ultraman tool has been run and all the Java code generated, including the code generated by ANTLR. Two bodies of code have been written by the user, the original application (including a small amount of extra initialization code) and the Ultraman transformation actions which implement the transformations. One body of code, the lexer/parser pair has been generated by Ultraman, although by way of ANTLR. This code performs the pattern matching and other internal Ultraman-related tasks as well as making calls into the user code for transformation actions. The final part of the system is Ultraman run-time code which provides all the support classes for the parser and lexer as well as providing Shadow Objects for the convenience of the user level code.

17 60 The arrows in the diagram indicate calls that are made from one part of the code to another. These arrows in the diagram are not meant to be all inclusive, but rather give the reader the general impression of how the pieces of code work together. The arrows are arranged chronologically from top to bottom (in terms of their point of origin), although the initialization arrow obviously is executed only once. The latter three arrows form the main loop of Ultraman execution: User code notifies Ultraman of a change in the application, Ultraman matches patterns and calls back into user code to perform transformations, and the transformations utilize the Ultraman library s shadow object for doing the actual screen updating. Of critical importance here is to understand that all of these pieces of code are encoded as Java classes and are all linked together in the final application. From the standpoint of the end- programmer, the only part of the generated code that he or she needs to be aware of is the entry point to inform Ultraman of a change to the application s state, or, more correctly, a change to a source tree that an Ultraman-derived interface depends on. The remainder of the lexer/parser pair is opaque to the end-programmer and should probably not be modified or manipulated. (One of the primary reasons not to modify the lexer or parser is that substantial amounts of machinery are encoded there for assisting with the state preservation part of the Ultraman library. In particular, the value numbering scheme used by the state preservation system is tightly integrated into the parser in ways that could be quite surprising to the end-programmer.) As a general rule, the only Ultraman run-time APIs that concern an application programmer are those involving Shadow Objects. The application programmer needs to use these APIs at initialization-time and at the time objects are put into the result tree of a transformation.

18 61 User Code System GeneratedCode Initialization Parser And Lexer Pair Original OrgChart View Code Event Notification Callbacks Ultraman Run-time Ultraman Run-time Transformation Code Use of Shadow Objects FIGURE 3-8 Overview Of The Code In An Ultraman Application