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:
From the tutorial application's base directory, issuing the schema-export
command (an ant target) for the first time will:
$ cd demo-apps/ContactMgr
$ ant schema-export
Next, let's launch our application:
- compile the framework,
- compile the tutorial application's code,
- create an H2 database (in subdirectory db/ ),
- generate the necessary o/r mapping files for the application, and
- subsequently generates the actual database schema.
This command is simply a convenient way of launching the application
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.
$ ant run
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.
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).
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
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.
I promised I'd show you how to change the admin user's password.
Let's do this now:
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.
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, email@example.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.
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.
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
- Right-click on the admin user in the list
- Select the action Change Password
- You will be presented with a dialog and prompted to enter the new
password (twice, to guard against typos)
The search results will appear in the listing below the query you
Let's take this example one step further: click on Save Query.
At this point your screen should look something similar to figure
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
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).
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.
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
Also, notice how both developers and end users are empowered by this
model of building applications:
- From the pull-down menu on the left, select Person Name's Last;
- From the second pull-down menu, select the appropriate comparison
operation; in this case it does not really matter, let's pick contains
- In the text field on the right hand side, enter Suez (or whatever
last name you're searching for);
- Finally go ahead and click on the Find button to perform the
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.
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.
- 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
- developers' time is freed to work on higher business-value tasks
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.
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..
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.
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).
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
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