EasyDB is a simple yet extendible Graphical User Interface (GUI) to a relational database. EasyDB provides point-and-click access to database relations, affording the easy, safe, and graphically intuitive ability to browse and manipulate data from the database. EasyDB ensures that only single-record-at-a-time changes may be made to database relations, making it safe for the database novice to use with little to no instruction. EasyDB has been created to work with a Sybase relational database, but as a Java application it can eventually be extended to other database types given its use of Java's JDBC package. EasyDB has been tested on the Windows (95/98/NT/2K), Solaris, and Digital Unix platforms.
EasyDB can be run from Windows or Solaris currently. All that is required after the software is installed is that you have a user account on a database server. You must know:
The default Start routine that comes with the software requires those values to connect to the database. If you are a Java programmer, however, you can create and use your own "main()" to determine these values. EasyDB will look for these values in a properties file (located in your HOME directory, or in a location specified on the command line), or it will prompt you upon startup for any values it has not found.
java [ -Dprop_file="/home/myname/.easydbrc" ]
-classpath "/usr/local:jaxp.jar:jconn2.jar:parser.jar"
easydb.Start
database-name
[ -ext extension-file ]
This is optional. This specifies the name and location of the properties file, described below, which contains the user's database user name, password, and server-url. If this is not specified, EasyDB will look for "$HOME/.easydbrc" (on all platforms). Note, the value of $HOME varies on the different Windows platforms.
A 'trick' on Windows platforms to handle the change in $HOME on the different versions, is to tell Java exactly where you want $HOME to be by adding another command-line "-D" qualifier before the classpath, such as: "-Duser.home=C:\MyDir".
This is required. This tells Java where to find the EasyDB files. Note also that the files jaxp.jar, jconn2.jar, and parser.jar are required. They are obtained separately from Sun and Sybase. Be careful to use the correct separators - on Unix use the colon, on Windows use the semicolon. Enclose the entire classpath in quotes.
This is required. This is what specifies to Java the main program to run.
This is required. This specifies the name of the database to which the user would like to connect.
This is optional. This specifies the name of an EasyDB Extensions File to use during the session.
This is an example Properties file which shows the format:
# # Example EasyDB properties file # easydb.db_userid=put_your_db_username_here easydb.db_pswd=put_your_db_password_here easydb.server=jdbc:sybase:Tds:myserver.mycompany.com:9992
The above is to be used as a template. The user should insert their own user name, password, and server. The entire file can be read-protected from others by setting the appropriate permissions. Or, the password can be left out and EasyDB will prompt for it. The line for the user's server will be similar to the above, exchanging "myserver.mycompany.com" for the user's own info. A common port number is 9992, but it is not always the correct one. Check with the system administrator.
This is the first window that appears when EasyDB is run. This displays the user name, the database to which the user is connected, the server URL, and the list of available relations for the user to browse or modify. Double-clicking on a relation from the list, or selecting one and then clicking "Open Relation" will open up the Record Window for that relation.
Pops up a file-selection dialog to find an EasyDB extensions file that the user would like to load for their session. One can load any number of extensions files that they want, but any new extension loaded corresponding to an already loaded extension will overwrite the old value with the new. Newly loaded extensions will only affect actions/windows in EasyDB that occur/appear after the file is loaded.
Closes all open windows and connections to the database, and exits the program.
Displays this Help documentation. In order for EasyDB to find the Help, the URL to it at the user's location must be set as a constant named "help_url_app", in the extensions file. This should be done during installation.
Displays EasyDB version number and last build date.
This is the scrollable list of available relations for the user to browse or modify. Double-clicking on a relation from the list, or selecting one and then clicking "Open Relation" will open up the Record Window for that relation.
This is only enabled if there is a relation selected in the Relation List. Clicking this button will open up the Record Window for that relation.
Same as File -> Exit menu item. Exits the program.
This window displays a relation, on a record by record basis. Each field of a relation is shown (unless it is chosen to be hidden, see below). Pairs of field name labels and field values are displayed for every field. All SELECT, UPDATE, INSERT, and DELETE actions are performed from this window. If a SELECT query is made that returns more than one record, the user can step through each record with the directional buttons at the top of the window. For reference, the database and relation name are shown in the title bar of the window.
Clears the window of all values in all fields. This is most useful for a fresh SELECT query where the user only wants to input values in a single or a few fields. Leaves the last data set in memory.
Clears the window of all values in all fields and erases any data set in memory. The window becomes as if it had just been created from the main window.
Only enabled if there are fields hidden. Redraws the window with all fields shown.
Erases the current data set in memory and closes the window.
Shows the user the last SELECT query performed by EasyDB.
Allows the user to choose between "Interpret Text Wildcards" and "Wildcards as Literals". The former means that wildcards (e.g. "%", "_") can be used in SELECT queries and will be interpreted. The latter means that any wildcards used will be treated literally, that is the "=" operator will be used in all predicates in the where-clause of the query.
Allows the user to choose between "OR" and "AND" for the operator that will be used to combine all predicates in the where-clause of the SELECT query. The default is "AND".
Allows the user to choose between having field syntax checks "ON" or "OFF". If "ON", the user will be able to enter only allowable values into any fields that check their syntax. Using "OFF" disables this checking. The default is "ON".
This is only for users that are very comfortable with SQL. This takes the SELECT query that would have been generated and run by the user clicking the Select button, and puts it in a text window for the user to edit before submitting it to the database. This provides the user with the ability to perform complex SELECT queries that might not be possible within the GUI. For example, one can group predicates with different combinations of "AND" and "OR" using parenthesis in this window. Clicking "OK" in this window will submit the query and the results will appear normally in the Record Window.
If the installer has set up EasyDB with help for the relation, this menu item will be available. It generally is used to pop up some kind of helpful description of the current relation. Relation-level help may be set in the extensions file as a relation level extension named "help_text".
Displays EasyDB version number and last build date.
This area, in the top of the window, displays the index of the current record out of the total number of records in the data set in memory from the last SELECT query. If there has been no query, and thus no data in memory, it will show "0 of 0".
This button works like a CD-player style interface. Click it once to move on to the next record. The next record in the data set will be displayed in the window. If the current index is at the end of the data set, or if there is no data set, the button will be disabled.
This button works like a CD-player style interface. Click it once to return to the previous record. The previous record in the data set will be displayed in the window. If the current index is at the beginning of the data set, or if there is no data set, the button will be disabled.
This is only enabled if there is a data set in memory from a recent SELECT query. Clicking this button brings up the Spreadsheet Window. Note that the Next and Previous buttons will also change the selected record in the Spreadsheet Window if it is showing.
This area, in the middle of the window, displays all the fields in two columns of name-value pairs. If an "alias" has been set for a given field (via a field-level extension named "alias" in an extensions file), then it will be displayed to the left of the value, otherwise the actual field name in the database will be displayed. The value will be displayed in some kind of widget appropriate for its type.
Most fields will show up as editable text widgets, which can display a value as well as let the user type a value in. Some fields will have restrictions on the input allowed. For example, an integer field may only allow the characters "0" through "9" and "-" to be input. Other types of fields may have format restrictions, such as datetime fields. If a field has been specified as being a discrete type (via a field-level extension named "discrete_values" in an extensions file), then it will be displayed as a pull-down menu with only the allowed values as choices in the menu.
All fields also each have a pop-up menu attached to them. The menu is activated by right-clicking over either the field name or the field value. The following is the list of each of the default menu items that a field comes with.
Field Pop-up Menu Items
This menu item will clear the current field. Any user input or existing data from a SELECT query will be removed from the field.
This menu item will leave the current field as-is, and clear every other field in the window. This is particularly useful when a certain looked-for value is found in that particular field, and the user wants to do another SELECT where that value is an important condition.
This menu item will hide the associated field. This is useful when a user is looking at a table with a larger number of fields than they are interested in. This allows them to "hide" all the fields in which they are not interested, making the displayed window smaller and easier to view. A field that the user wants to always be hidden, during each session in EasyDB, can be specified via a field-level extension named "hidden" in an extensions file.
This menu handles the user's selection of the logic operator to be used in that field's predicate in the where-clause for the next SELECT query. All fields come with the "Negate" choice. Selecting it, for example, will change a query's where clause from
where field = value
to
where NOT field = value
If the field is a numeric type, then the choices also include the
sequential operators ( <=, <, =, >, >=, <> ) .
Selecting one of those, for example, will change a query's where
clause from
where field = value
to
where field >= value
This menu item will only appear for character-type fields whose values tend to be much larger than what is easily displayed in the text widget. This pops up a text-viewing/editing dialog where the user can see the full text or edit it. This is merely for convenience. Any necessary editing can also be done in the smaller text widget on the window, but this pop-up dialog may make the process easier.
This menu item will display any available user-specified help for the given field. Since EasyDB arranges itself based on what it learns from the database at run-time, the default is that there is no extra help information available for a field. However, a user can specify help information for a specific field via a field-level extension named "help_text" in an extensions file.
These are the defaults that the basic version of EasyDB uses. Since EasyDB is customizable, however, a user's version may include more menu options.
The four buttons shown in the window, "Select", "Update", "Insert", and "Delete", are how the user interacts with the database. For those knowledgeable about SQL, each one maps to an associated SQL command.
With the exception of the "Select" button, clicking any one of these action buttons has the ability to alter the database and so is logged to a file. Logging is overridable via extensions but the default behavior is to log all database changes to the file "$HOME/.easydblog" on Unix or the file "$HOME\easydb.log" on Windows. Again, note the value of $HOME varies on the different Windows platforms.
This performs an SQL SELECT based on the values in the fields in the window. It combines all the fields that are shown and that have values to create a where-clause for the query. For example, if only one field has a value, it would create a query that is the equivalent of
select * from relation where field = value
If there are no fields with values, then it selects all records from
the relation. Thus, if the user clicks the "Select" button immediately
after the window appears, they will retrieve, and be able to step
through (one record at a time), all the records in the relation.
SELECT queries with where-clauses that include more field/value
predicates will further refine the set of records found.
The set of records found is often referred to in this document as "the data set in memory".
This performs an SQL UPDATE based on the values in the fields in the window. The Update action updates an existing record in the database, and so it requires that a copy of that record be listed in the data set in memory from a previous SELECT query. The Update action will only update those shown fields whose values have been altered from how they appeared in the database.
A dialog window will appear asking the user to confirm the action, and if the user agrees, the record will be updated in the database.
As a precaution, EasyDB only allows one record to be updated at a time.
This performs an SQL INSERT based on the values in the fields in the window to create a new record in the relation. Because EasyDB would like to insert only a complete record during this action, both shown and hidden fields will be used for the INSERT. If there are hidden fields, the user will be warned that the data in the hidden fields will be used, whatever it may be.
A dialog window will appear asking the user to confirm the action, and if the user agrees, the new record will be created in the database.
As a precaution, EasyDB only allows one record to be inserted at a time.
This performs an SQL DELETE of the current record shown in the window. The Delete action deletes an existing record from the database, and so it requires that a copy of that record be listed in the data set in memory from a previous SELECT query.
A dialog window will appear asking the user to confirm the action, and if the user agrees, the record will be deleted from the database.
As a precaution, EasyDB only allows one record to be deleted at a time.
This area, at the very bottom of the window, is where any messages will appear if the user needs to be notified of something. For example, if there are any fields hidden, this will display a message to that effect. This will also display messages alerting the user if they have just stepped to a record in memory that they had recently altered and is now different in the database than it is in memory (and they need to perform a new SELECT to see this).
Messages informing the user of records that have been updated or deleted will be shown in color. The default colors are: ORANGE for updated records, RED for deleted records. These same colors will be used to denote altered records in the Spreadsheet Window.
This window shows a read-only view of the current data set in memory, in a spreadsheet type format. This allows all the records to be viewed in one place. This is useful to get a global look at the records in the data set. Because EasyDB is concerned with 'safe' database access, this is merely a read-only view - all alterations to the database must be made through the Record Window, one record at a time.
This window shows the database and relation being used, the number of records in the data set in memory, the SELECT query used to retrieve the data set, and the records themselves in a table view.
Same as the "Copy" button at the bottom of the window. This pops up a copy-table dialog which allows the user to copy the current contents of the window to a file or to the terminal. This is useful for generating text reports from sessions in EasyDB.
Closes the Spreadsheet Window. Does not affect the data set in memory.
Displays EasyDB version number and last build date.
The top of the window shows the current database and relation being used, and in an uneditable text box shows the SELECT query used to generate the current data set in memory.
The main part of this window is the table view of the data set. This shows a column for each shown (not hidden) field in the Record Window, and a row for each record of the data set in memory resulting from the most recent SELECT query.
The highlighted row of the table corresponds to the current record showing in the Record Window. Selecting a different row of the table will update the current record displayed in the Record Window. This can be a quick way to jump around the data set in memory.
With large database relations, the number of records found by a SELECT query can be very large. Therefore EasyDB defaults to showing only up to the first 100 records of the data set in this window. While the total data set size (listed at the top of the window) is still larger than the maximum shown in the table view, the user can increase the maximum by clicking the "More" button. This will continue to double the amount shown (and brought into memory) until either: the total size of the data set is reached, or the resource limits of the user's machine are met.
The default maximum for each table view is 100 when the user starts their first session in EasyDB. This initial maximum however can be changed simply by specifying a new value via a constant named "sheet_init_max_rows" in an extensions file.
Increases the maximum number of rows shown in the table view as discussed above. This button is only visible if the data set is not fully loaded into the table view, due to the maximum being met.
This pops up a copy-table dialog which allows the user to copy the current contents of the window to a file or to the terminal. This is useful for generating text reports from sessions in EasyDB.
EasyDB was created first and foremost to provide easy, safe access to a relational database for users spanning multiple different projects and applications. However, EasyDB is also very customizable for those users that have their own special needs and interests.
EasyDB handles all settings and customizations together in a single format, namely in an EasyDB Extensions File, which is written in XML. The user need not be fluent in XML to create/modify an extensions file, so long as there is a text editor handy. The sample file below can be used as a template.
EasyDB loads extensions two ways:
The user can load and reload extensions at anytime during their session. When extensions are loaded, values for any previously un-set extensions are added, and values for previously loaded extensions are overwritten. This gives the user the capability of writing their own short extensions file that has a few settings that they might load after using their group's extensions file, for example.
The best way to describe the extensions file is to show the following sample and discuss its elements. The sample extensions file
is made up of the following tags:
This is the root tag for the XML file. All data in the file must
exist as a sub-tag of this root tag.
XML NOTE: In general, all tags (words enclosed by < and >)
in XML must have corresponding end-tags to close them. The corresponding
end-tag for "<easydb_extensions>" is the tag
"</easydb_extensions>" which occurs at the end of the file.
This is one of the two accepted child-tags of "easydb_extensions". The other is "database", see below. This tag is parent to all the following items that represent application-wide settings.
A web browser is used to pop up some of the larger help HTML documents such as this page. This extension is used to specify a path to the browser, if it will not be found in the user's $PATH environment variable. If it is already in the users path, then leave this tag in with no text in it. If this tag is not found, it is a signal to EasyDB to not try to show any HTML help.
Currently, Netscape is the only supported browser.
Specifies the URL of this help page after it is installed locally.
Advanced extension. Specifies the location of a user-written plug-in logger class. Must extend EasyDB's DbLogger class to be accepted. Will be loaded dynamically at run-time, if found in the classpath.
The number representing the choice for the initial maximum number of rows shown in the Spreadsheet Window. The default is 100 if this is not specified.
If the user has written their own plug-in type classes for EasyDB, they can insert any of their own constants here. This can be named anything the user wants except the names of other tags listed here.
This is one of the two accepted child-tags of "easydb_extensions". The other is "constants", see above. Note that this tag has, what in XML is called, an attribute. Its only attribute is named "name" with the value "mydatabase", written as name="mydatabase". That means that all of the extensions that are rooted under this tag can only be applied to relations and fields in the database named "mydatabase". If the value of the name attribute was "everydb", then all its extensions would apply to every database that EasyDB encounters.
NOTE - the values "everydb", "everytable", and "everyfield" are special values. They are like wildcards that will match any database, relation, or field (respectively).
This tag is parent to all the following extensions specific to the stated database:
Represents a relation under the above listed database. The value of the "name" attribute specifies the name of the relation to which these extensions will be applied. If the value of the "name" attribute is "everytable", then all of the extensions that are rooted under this tag will be applied to every relation encountered in the above listed database.
Specifies the help text blurb for the specified relation. If specified, this text is accessed under the Record Window's Help menu. This is referred to as relation-level help in this document.
Advanced relation-level extension. Specifies the location of a user-written plug-in data-action class. Must extend EasyDB's DbDataAction class to be accepted. Will be loaded dynamically at run-time, if found in the classpath. A data-action class performs any query-time data actions that the user requires, after a modification is made to the specified relation. A data-action is triggerred immediately after the modification is made to the database.
Represents a field under the above listed relation. The value of the "name" attribute specifies the name of the field to which these extensions will be applied. If the value of the "name" attribute is "everyfield", then all of the extensions that are rooted under this tag will be applied to every field encountered in the above listed relation in the further above listed database.
Specifies a phrase to be shown in the GUI instead of the actual database field name. This would appear in the Record Window as the label to the left of the field's value.
Specifies a set of comma-separated discrete values that can be used for this field. If specified, then the user will only be able to input a value from this list, for this field. The default behavior is for such a field to appear in the Record Window as a pull-down list.
Specifies the help text blurb for the specified field. If specified, this text is accessed in the Record Window when the user right-clicks on a field and selects "Help on Field". This is referred to as field-level help in this document.
Specifies that this field is not to be shown in the Record Window. If there are hidden fields, the user will be notified with a message at the bottom of the window and allowed to show all fields again via a View menu item.
Advanced field-level extension. Specifies the location of a user-written plug-in DbField- generating Java class. Must extend EasyDB's DbFieldCreator class, and be able to generate a class extended from EasyDB's DbField class for this specified field, in order to be accepted. Will be loaded dynamically at run-time, if found in the classpath. The widget created by the plug-in class will be shown in the Record Window for the specified field.
Advanced relation-level extension. Specifies the location of a user-written plug-in relation class. Must extend EasyDB's DbRelation class to be accepted. Will be loaded dynamically at run-time, if found in the classpath. Requires a significant knowledge of the EasyDB software.
As this document shows, there are a lot of possible customizations a user can make to EasyDB. It is advisable to start with the included sample extensions file and go from there.
Return to the top of this page.