Chapter 3
A Short Tour

Let's take a first look at a software application developed using JMatter. We're going to setup and launch, and then study the Contact Manager demo application that is bundled with JMatter. You will find it in demo-apps/ContactMgr.

3.1  Launching ContactMgr

Follow these steps8:
$ cd demo-apps/ContactMgr
$ ant schema-export
From the tutorial application's base directory, issuing the schema-export command (an ant target) for the first time will:
  1. compile the framework,
  2. compile the tutorial application's code,
  3. create an H2 database (in subdirectory db/ ),
  4. generate the necessary o/r mapping files for the application, and
  5. subsequently generates the actual database schema.
Next, let's launch our application:
$ ant run
This command is simply a convenient way of launching the application during development.
JMatter applications are designed to be multi-user applications, running in client-server mode. The framework supports the task of deploying applications using Sun's Java WebStart technology. Please refer to chapter 18 for complete documentation pertaining to deploying applications.
If you prefer to configure your own MySQL or PostgresQL database, please refer to appendix B.

3.2  The Tour

OK, we've just launched our first JMatter application. We should be greeted with the login screen shown in figure 3.1.
Figure 3.1: Contact Manager Login Screen
When an application is first created, a single user will exist in the system. The user name and password values are admin. Later on, we'll show you how to change the admin password.
Go ahead and login. You are now presented to your application's desktop (see figure 3.2).
Figure 3.2: Contact Manager Application Desktop

3.2.1  A Quick Orientation to the User Interface

On the left hand side you see a toolbar. This toolbar is a little different from most application toolbars. Instead of containing various actions (such as copy, paste, and others typically found in a word processing application, for example), this toolbar contains types of things: Persons, Businesses, Users, Folders, etc.. I'm going to call this toolbar the Class Bar from here on. Furthermore, I will often reference the term as a single, lower-cased word: classbar.
The JMatter user interface was designed to be simple and easy to understand. The mechanism for communicating various activities to the application mirrors the way we naturally tend to think about how to perform actions. We first identify the object in question, and then specify the action to perform.
In JMatter applications, when an object is displayed in a minimized form (which is the case with the various objects we see in the classbar), the various actions to invoke are accessible via a context menu, summoned by right-clicking on the object in question.
This gesture should be a familiar one. For example, on the windows desktop, right-clicking on a file or folder will "bring up" its context menu. On the MacOS with a two-button mouse, it's the same gesture (simulated as a ctrl-click on a 1-button mouse). GNU/Linux-based desktops have the same metaphor. The mechanism of first selecting an object, and then selecting an action is known as a noun-verb user interface metaphor9.
So for example, to browse the list of users defined in the system, you can move your mouse to the Users icon, right-click on it and a menu of actions will appear. One of these actions is the Browse action. Go ahead and browse Users. You should see something similar to figure 3.3.
Figure 3.3: Users
I promised I'd show you how to change the admin user's password. Let's do this now:
  1. Right-click on the admin user in the list
  2. Select the action Change Password
  3. You will be presented with a dialog and prompted to enter the new password (twice, to guard against typos)
The next time you log in to the application, you'll have to enter the new password. JMatter stores an md5 hash of the password in the database and so passwords are not vulnerable to prying eyes.
Close the window containing the listing of users for now. Let's go ahead and add a person to our contact manager. You've probably already guessed how to do it: right-click on the Persons icon in the Class Bar. Sure enough there's an action on its context menu called New. That's the one.
Your screen should now look like figure 3.4.
Figure 3.4: Creating a new Person
Go ahead and complete the form. Note that there are two tabs' worth of information to enter: the person's name and their contact information. Furthermore, the second tab contains a collapsible element: the address portion of the contact information can be expanded to reveal the address fields (street, city, state, zip, etc..). After you've finished entering the information, go ahead and click the Save button. Your view of the information you just entered will change to a read-only mode. To edit the information further, click the Edit button. Don't worry if you closed the window. Your information has been saved and you can retrieve this new person's information at any time. Note that other users logged in to the system can also view the contact information for this new person.
Right-click Browse on Persons to view a listing of all the persons in your system. If you have a system with 300 persons in them, JMatter will make sure to page the listing 15 entries at a time10. Also, notice that if you modify the Preferred Contact Method for a person from, say, Home Phone to Email, then when you're viewing that person in a minimized context (say browsing through a list of persons), the title for that person will automatically change. In the former case, it might say Joe Burns, (512) 333-444 and in the latter case it will change to Joe Burns, jb@yahoo.com.
You can also create objects of type Business, for example, if you need to keep track of contact information for various businesses that you interact with. The mechanism for performing CRUD11 operations on any type (Person, Business, User, etc..) is the same.
Lastly, notice that you can delete persons, though we want to prevent the possibility of accidental deletion of important information. JMatter does this by protecting the Delete action with a lock. Just click on the lock first to unlock the action and then click on the button to perform the deletion.
It's important to note that JMatter applications' user interfaces are very simple: they boil down to the implementation of a single concept: the noun-verb user interface metaphor. That is, we're in a world of objects and we manipulate them through actions12.

3.2.2  Folders

Notice the Folders icon in the classbar. Right-click the New with name action, and specify a name for the new folder you're creating. Let's say that you want to keep track of important contacts, in which case you might want to name the folder Important Contacts. After entering the folder name, click OK. The folder is created and displayed on the screen.
From a listing of Persons, you can simply drag and drop an entry onto the folder to add that person. You can put pretty much anything you want in a folder. The concept is completely analogous to the notion of folders on Operating System desktops. The difference of course is that you are not putting folders and files into a folder, but any type of object that is defined by the application, including Folders, Persons, Businesses, Queries, and more.
Drag and Drop is only one mechanism to add items to a folder. I'll be showing you other ways of doing the same thing later on.

3.2.3  Queries

Assume you have plenty of contacts in your contact management system. This is not a problem of course since the application is backed by a database management system, designed to hold thousands of records, gigabytes of information. The primary advantage of a database of course is its ability to mine information.
I'd like to look up all members of the Suez family in my contact manager. Here's one way to do this using JMatter: right-click on Persons in the Class Bar and pick the corresponding action, which this time will be Find.
When invoking Find on Persons, a window will appear containing a way for us to specify a query. This one will be fairly easy:
  1. From the pull-down menu on the left, select Person Name's Last;
  2. From the second pull-down menu, select the appropriate comparison operation; in this case it does not really matter, let's pick contains
  3. In the text field on the right hand side, enter Suez (or whatever last name you're searching for);
  4. Finally go ahead and click on the Find button to perform the query.
The search results will appear in the listing below the query you just performed.
Let's take this example one step further: click on Save Query. At this point your screen should look something similar to figure 3.5.
Figure 3.5: Performing and Saving a Query
Give your query a name (I called it The Suez's) and click Save. We've just defined and executed a query, then named it and finally saved it.
It turns out that in JMatter, a query is nothing more than yet another type of thing, like a Person or a Business. That's why there exists an entry in the Class Bar called queries. Go ahead and browse queries (right-click Browse on Queries in the Class Bar) and you'll see your new query show up in the list (see figure 3.6).
Figure 3.6: Browsing Queries
If you like, you can even query queries. This may sound far-fetched but after a while, after you've defined lots of queries, the ability to search for a query (by name) might come in handy.
Now that your query is defined and saved, you can execute it at any time. You guessed it, just right-click the Execute action on any query listed and you'll get the search results. If another matching entry is entered into the system after a query is created, the search results will include the new entry as well, of course. JMatter calls this feature a Smart List.
Finally, since the query we just saved was a query on Persons, JMatter went ahead and established an association between the Persons type and this new query. It took the liberty to add a new action to the Persons context menu. That is, you can now right-click The Suez's on Persons.  Quick Recap

I know we haven't yet reached the chapter about actually writing applications in JMatter. Still, it's important to note even at this early stage that the query facilities baked into this application are provided by the framework. You will not find a single line of code in the Contact Manager application to support these capabilities.
Something should be clicking at this point. Attempt to quantify how many lines of code exist in a "traditional" software application to support searches; especially for a category of application such as an issue manager. Issue managers are all about entering and updating and searching issues. Since entering and updating and searching things is built-in in JMatter, then very little work actually remains: the need to define that there exists such as thing as an issue. That's about it.
Also, notice how both developers and end users are empowered by this model of building applications:
  1. end users do not have to go to a developer in order to define a new query in the system, they can do it themselves
  2. developers' time is freed to work on higher business-value tasks

3.2.4  Logs

To really drive the notion that all kinds of objects can play in the JMatter sandbox, so to speak, have a look at the type called Log in the Class Bar. Browse the list of log entries and you'll see a screen that looks like figure 3.7.
Consider revising Log title to include User (who) property and rebuild screenshot, so it shows "admin" logged in, "eitan" logged out, etc.. Same goes for "Object" updated, which becomes "Eitan Suez" updated. Lastly, finish implementing delete as a move to the deleted table rather than a real delete to prevent integrity constraint issues in the db when an object cannot be deleted because another object still references it.
Figure 3.7: Log Listing
What we discover is that the framework keeps track of specific events such as when a user logs in or out of the system or when a specific piece of information is created or updated13. The system creates a log entry: a message, possibly a longer description of the event that took place, who performed the specific action, and what object this action was performed on. Since log objects are proper JMatter objects (like Person and Business) they inherit the same benefits: the ability to search through logs, to view and even edit logs (though technically that last bit should be forbidden, and can be made so14). You can also see in figure 3.7 that the listing is currently showing you the first of two pages of logs, with a page navigation arrow at the bottom.

3.2.5  Multiple Views

Before we end our tour, there's one last major aspect of the user interface that we need to discuss: the notion of multiple views.
You might have noticed four little icons on the top right-hand-side of listings windows. Bring up a listing of persons (right-click Browse on Persons) and click on the icon with the yellow star in it. You should see something similar to figure 3.8.
Figure 3.8: Icon Alternate List View
The user interface for the Contact Manager application basically provides multiple alternative ways of viewing information. You can view a listing of Persons (or Queries or Logs) as a simple listing or as a list of Icons, or as a table, with the Person's fields (name, contact information) laid out in separate columns, or as a composite view: a listing on the left-hand-side combined with a form view of the currently selected item on the right hand side. This notion of multiple views should feel familiar, as it's akin to the way file managers on our desktops behave: we can view a listing of files and directories in detail view or iconized view and so on.
For single objects, say a single contact, you will likewise find alternate views. You can use a tree view for a contact where the tree is arranged in such a way that associations between objects can be traversed. So for example, we can lookup a log entry about someone logging in to the system and view that entry in a composite tree view, as shown in figure 3.9. By expanding the tree nodes we can discover some of the associations between log objects and other objects. In this case, the person who logged in was the administrator. We also discover that users can be assigned to roles. The admin user belongs to the Administrators role, which in turn also keeps a list of all the users in the system that have the same role. Finally we see that roles maintain lists of field and command restriction objects. It is by adding such restrictions to roles that we can begin to specify an authorization policy for our system: who is allowed to view what fields, who is allowed to invoke what actions, etc..
Figure 3.9: Composite Tree View for a Log Object
So this composite tree view is actually a wonderful way to explore and quickly learn the way information is modeled in a system, the various associations between types of objects, and how to traverse them. In chapters 5 and 6 we'll have a chance to explore such relationships.  Custom Views

Going back to the notion that we can have multiple different and complementary views for objects or lists of objects: certain types of objects have additional custom views, specific to that type. For example the Class Bar is nothing but a custom view of a folder of folders. Although I won't show you how to do this until section 4.5, you can look for a special folder named Class List whose contents are reflected in the Class Bar.
Figure 3.10 shows a composite tree view of the class bar. You can right-click Browse or New on any of the three views of the Persons type, for example. Furthermore, it is possible to customize the class bar by placing other types into that folder (for example the Role type, which would be useful for system administrators who sometimes need to define a new role, or add new users to an existing role).
Figure 3.10: Three Views of the Class List Folder: A tree, an icon list, and the class bar
This brings up an important point about the philosophy behind the design of the JMatter framework: to the greatest extent possible, the JMatter framework strives to give the end user more control of the application, more independence from the developer. How often have you been in a position where you really wanted to make a simple change to the way an application is configured only to find out that the change could not be performed from its user interface (i.e. it required programming)?

3.2.6  Tour Summary

Let's review what we've accomplished so far.
We've seen how to launch the Contact Manager application, log in, and create a new user if we wish to. We learned how to browse and create contacts, and once our contact list becomes very large, how to make practical use of the query feature to find the information we're looking for. We also know how to switch between alternate views of the same information, and have a good grasp of what JMatter applications are all about, from the end user's perspective.
Finally, we have a general understanding of the noun-verb metaphor that JMatter application user interfaces model. That is, the notion that one first selects a target object on which to perform an action, and then looks for and invokes a specific action on that object. This knowledge should enable us to quickly learn the user interfaces of other applications written with JMatter, even ones we're encountering for the first time.
In the next chapter, we'll start exploring how to write JMatter applications. We'll build our own contact manager. You may or may not be surprised by now if I were to tell you that the task will take us only a few minutes.

Part 2
Tutorial Applications