Tabulator can be driven from the command line, or through a web application. Both of these use the same match expression language during searches.
It comes with a number of examples, and in this text we'll use the
Music Database example.
This is a good choice as it has no external dependencies on databases,
messaging systems or anything else, and so if you have Java,
you can easily repeat what you see here yourself.
Here we assume it is unzipped into /tab_music.
Command line
To learn the command line arguments :-
$ /tab_music/bin/Tabulator -help
usage: Tabulator [flags]
flags: -config configspec configuration class (and arguments)
-type type data type to select from
-group group include attribute groups
-match attr expr where attribute matches expression
-out file output filename (default: is stdout)
-format fmt output format (csv, tsv, psv, html, xml, json)
-run execute query
-describe describe configuration or selected type
-verbose show query plan and execution information
The Tabulator script in this directory runs Tabulator,
and passes the -config ConfigurationMusic argument,
which identifies the configuration class for the music database.
Tabulator instantiates this class, which is how it gains access to
the various types
of data, and the attributes they contain.
To describe the configuration that Tabulator is using :-
$ /tab_music/bin/Tabulator -describe
Configuration: Music
Type: artist
Attribute: artistid
primitive type Integer
can't be NULL, searchable, not required for search
values match pattern: [0-9]+
part of primary key, not computed/enriched
... much more detail
To describe just one of the types in the configuration :-
$ /tab_music/bin/Tabulator -type artist -describe
To issue a query against the "artist" type. We're looking for all artists that don't have the word "repetitive" in their "comments" :-
$ /tab_music/bin/Tabulator -type artist -match comments 'NOT LIKE "%repetitive%"' -run artistid,name,comments 2,Tangerine Dream,A German electronic music group founded by Edgar Froese 3,Ultravox,An English new wave band 4,Yello,A Swiss electronic band consisting of Dieter Meier and Boris Blank
The NOT LIKE "%repetitive%" is a
match expression, which is like a SQL WHERE
clause, but in a Tabulator specific language.
It is possible to run multiple queries in the same run. This can be handy if loading the configuration takes time.
It is also possible to output data to files, and in various formats. It doesn't output to Excel format, but that's not normally an issue, because Excel can read the XML format that it does write.
Summary: In general each query will want to set the type, add zero or more attribute groups (so that their attributes are available for matching and in the results), specify zero or match expressions, specify the output file and format, and then run the query.
This is very similar to the following in SQL:
SELECTing the table to query FROM,
choose the columns in the result,
specify the WHERE clauses (each applying to one column),
and then run the query.
Web application
Tabulator uses the nyangau.se Servlet Engine. This means there is no dependency on a web server (such as Apache HTTPD), servlet engine (such as Apache Tomcat) or other web infrastructure. You can just run it :-
$ /tab_music/bin/TabulatorServer Visit http://localhost:5050/tab Userid guest password guest can see artists, albums and tracks Userid andy password andy can see all types
It will stay running until you break into it.
If you want to run it in the background, and have it start at boot time,
the package includes a sample control (start, stop, status) script to work
from and a sample initscript to put in /etc/init.d.
These will require a little customisation.
Access to Tabulator can be restriced to authenticated individuals,
and each of those individuals can be authorized to access to specific types,
or to all types.
This is controlled in the TabulatorServer.props file,
and this is described later.
Some of the configuration (particularly that relating to logout) has to be
left unchanged, as this is required to ensure it is possible to logout
of the application properly (as it uses basic authentication).
For a properly secure solution, access via HTTP should be disabled,
and access via HTTPS enabled.
HTTPS then protects login credentials and business data.
For now, note the message displayed by TabulatorServer above.
Page structure
The main active portion of the application is comprised of 4 main pages :-
In the diagram above, the grey boxes are web pages. The arrows (with solid arrowheads) show most of the standard navigations you get for moving from page to page. The navigations appear as buttons you can press. aType is a placeholder for the specific data type you have selected.
The first screen is the types page, from which you select the type you'd like to search.
The search page allows you to input match expressions to select match the values for the given attributes. Note that because the "extras" attribute group checkbox is ticked, we see the "year" attribute displayed, and we can search on it.
The list page produces a list of results matching the supplied match expressions. Note that there are options to fetch/download the results in various other formats. If the search didn't produce the results you expected, use the Refine search button to go back and refine it - avoid the browsers back-button. Also, watch out for when this screen reports that it is only showing the "first search results (there could be more)", and note that sorting on any of the columns is only sorting the data returned by the query. You may also get an option to "Show query details", which depending on the type being searched or the source from which that type gets its data, may show you details of the query executed, and observations during execution.
The show page shows all the attributes for a selected instance of a type.
Search similar would take you back to a search screen with
all the search match expressions populated with the attribute values from
this screen (except very large ones).
The idea is that you'd keep most expressions and change a few, perhaps to
wildcards.
The addressable web
An original design principle of the web was that content on it be addressable by its URL.
To this end, the Tabulator web application makes no use of session. Everything about where you are in the interface is encoded in the URL. This means you can bookmark any of the main (non-documentation) pages and come back to them later.
This includes search screen parameters.
This is the reason there is a Form to URL button - it transports the
current form search values into the URL, so you can cut-and-paste the URL
into an email and send someone.
When they visit the URL, they get your search parameters pre-loaded.
URL to Form does the reverse, it transports the URL parameters into
the form (undo-ing any edits you may have done), and is in fact the
forms Reset button in disguise.
Navigations
The web application version of Tabulator has a significant advantage over the command line version - it allows for the easy interactive navigation between types.
Consider that in the Music Database example, an artist has a number of albums, and each of these has a number of tracks. Further each track can have a number of reviews. Clearly it would be great if when displaying an album, it would be possible to navigate to a list of tracks on the album. Or, from an album to the artist that produced it. There are many other such obvious and handy navigations.
This diagram only shows the list and show pages, and the hollow arrowheads show additional navigations that are available :-
One thing you may be wondering is why isn't there an arrow from list track to list review? The answer is that there could be. In the implementation of the "Type" class for the type "track", a decision has been made that the Reviews button is to be presented when showing a specific track, but not when presenting a list of tracks. The Music Database example is very simple, but with a much more complicated data model, there could be many many possible navigations. Although you might want the ability to perform any of them (and so place them on the show page) you may not want to clutter up every row of the list page with them.
It is also possible that navigations are present (or not) depending on the particular data values. We could, for example, decide only to show the Tracks in all albums navigation only for the artist Philip Glass. This feature is particularly useful when types contain optional attributes that when present, link to other types.
If a navigation appears pink, this means you are not entitled to view
the target data type.
If a navigation appears red, this means the code (ie: the "Type" class)
for the the target data type is not present in the running copy
of Tabulator.
Extended navigations
The normal actions supported by Tabulator have been described above,
ie: search, list and show.
You see these values in the URL, preceded by action=.
It's possible to create a navigation with a different action. These are referred to as extended actions, in that they are an extension to the set of actions understood by Tabulator.
A method in the type class is invoked, passing the chosen extended action, Match expressions and values.
If the method recognises the action, it generates the page content and returns true, otherwise it returns false. It can return any content-type, and it has access to the methods in the TabulatorServlet for providing header, trailer and errors, if required.
For example, in the Fishy Database example, there is an extended action which shows the raw XML page behind a specific fish type. Also, the QPid message type implements an extended action to allow you to download the message content.