Developed at the

Polish-Japanese Institute of Information Technology

Chair of Software Engineering

SBA and SBQL home pages

© Copyright by ODRA team, © Copyright by PJIIT

 

 

ODRA – Object Database for Rapid Application development

Description and Programmer Manual

 

 

by Mariusz Trzaska and the ODRA team

 

5. ODRA Integrated Development Environment (IDE)

 

ODRA Integrated Development Environment (IDE) simplifies the process of creating ODRA programs and managing an ODRA server. When we have decided to provide an IDE, two approaches were considered:

·        implementing the whole IDE from a scratch,

·        utilizing some components or libraries providing partial functionality for our environment.

The first approach guarantees more power and flexibility and does not restrict our freedom in designing the IDE. However the cost is significant development effort. The latter solution limits functionality and design by constraints coming from the utilized components. It also requires extra learning. However, after some research we have chosen to follow the second approach. The main reason was to focus on implementing ODRA specific features rather then on usual text editor functions.

After some analysis we have chosen a text editor called jEdit (http://www.jedit.org/) as a primary text editor component for our ODRA IDE. The editor has been modified and surrounded by dedicated plugins providing easy access to the ODRA system.

5.1 Text Editor

According to jEdit’s creators, the software is a mature programmer's text editor with hundreds (counting the time developing plugins) of person-years of development behind it. While jEdit beats many expensive development tools for features and ease of use, it is released as free software with full source code, provided under the terms of the GNU General Public License.

The core of jEdit was originally developed by Slava Pestov. Now the jEdit core, together with a large collection of plugins is maintained by a world-wide developer team.

5‑1. Screenshot of the plain jEdit

Fig.5-1 shows a screenshot of the plain (original) jEdit in action. Due to its highly customizable interface the number of possible configurations is very high. Fig.5-1 shows only one of many possible configurations.

Some of general jEdit's features include:

·        Written in pure Java, so it runs on Mac OS X, OS/2, Unix, VMS and Windows.

·        Built-in macro language; extensible plugin architecture. Dozens of macros and plugins available.

·        Plugins can be downloaded and installed from within jEdit using the "plugin manager" feature.

·        Auto indent, and syntax highlighting for more than 130 languages.

·        Supports a large number of character encodings including UTF8 and Unicode.

·        Folding for selectively hiding regions of text.

·        Word wrap.

·        Highly configurable and customizable.

Below we enumerate some detailed jEdit features taken from the official web page:

·        Combines the best functionality of Unix, Windows and MacOS text editors.

·        Runs on any operating system with a Java 2 version 1.3 or higher virtual machine - this includes MacOS X, OS/2, Unix, VMS and Windows.

·        Efficient keyboard shortcuts for everything

·        Comprehensive online help

·        Unlimited undo/redo

·        Copy and paste with an unlimited number of clipboards (known as "registers")

·        Register contents are saved across editing sessions

·        "Kill ring" automatically remembers previously deleted text

·        Rich set of keyboard commands for manipulating entire words, lines and paragraphs at a time

·        "Markers" for remembering positions in files to return to later

·        Marker locations are saved across editing sessions

·        Any number of editor windows may be open, each window may be split into several areas, each area can view a different file. Alternatively, different locations in one file can be viewed in more than one area

·        Multiple open windows and split windows are remembered between editing sessions

·        Rectangular selection

·        Multiple selection (sometimes known as "discontinuous" or "additive" selection) for manipulating several chunks of text at once

·        Word wrap

·        Syntax Highlighting

·        Source Code Editing

o       Intelligent bracket matching skips quoted literals and comments

o       Auto indent

o       Commands for shifting the indent left and right

o       Commands for commenting out code

o       Soft tabs option

o       Abbreviations

o       Folding, with two fold modes: indent-based, and explicit (where the buffer is parsed for "{{{" and "}}}")

·        Search and Replace

o       Both literal and regular expression search and replace supported

o       Multiple file search and replace; search in either the current file, all open files, or all files in a directory

o       "HyperSearch" option to show all found matches in a list

o       Reverse search supported

o       Incremental search supported

o       Option to replace occurrences of a regular expression with the return value of a BeanShell script. As far as we know, no other text editor offers comparable functionalities.

·        File Management

o       Any number of files can be opened at once

o       Supports a large number of character encodings including UTF8 and UTF16

o       Automatic detection of several character encodings (4.2)

o       Automatic compression and decompression of GZipped (.gz) files

o       Any character encoding supported by Java can be used to load and save files

o       Multi-threaded I/O system supports pluggable "virtual file systems" for listing directories and loading files:

v     FTP plugin adds support for loading and saving files on FTP servers

v     Archive plugin adds read-only support for loading files from ZIP and TAR archives

o       Custom file system browser component used in open and save dialog boxes

o       Powerful keyboard navigation in the file system browser

o       Files can be deleted and renamed, and new directories can be created from the file system browser

·        Customization

o       Syntax highlighting modes are defined for XML files; new modes are easy to write

o       Many editor settings can be set on a global, per-mode, or per-file basis

o       Fully customizable keyboard shortcuts

o       Fully customizable tool bar and right-click context menu

o       Macros to automate complex editing tasks can be written in the BeanShell scripting language

o       Macros can be recorded from user actions

·        Extensibility

o       Plugins can turn jEdit into a very advanced XML/HTML editor, or a full-fledged IDE, with compiler, code completion, context-sensitive help, debugging, visual diff, and many language-specific tools tightly integrated with the editor.

o       More than 150 plugins are already available that add a variety of features to jEdit.

o       The "Plugin manager" feature downloads and installs plugins (and updates) from within jEdit automatically.

o       Plugin windows can either be shown as separate, top-level frames, or as "docked windows" inside the jEdit editor window.

It can be seen that utilizing jEdit makes ODRA IDE really powerful in the scope of working with source code files.

5.2 Installing and Running

In order to install ODRA-IDE the user has to follow the procedure described below:

·        Install Java JRE or JDK (Java SE 6 or later is required by the ODRA). You can download it from: http://java.sun.com/javase/downloads/index.jsp.

·        Extract the ODRA downloaded archive (ODRA-IDE_x.rar).

·        Run ODRA-IDE.jar. If *.jar file extension is not properly associated, try this:

<JavaBinPath>\javaw.exe -jar <extracted IDE path>\ODRA-IDE.jar

Make sure that the IDE directory is the current one. After successfully run you should see a splash screen with the progress bar and the IDE itself (Fig.52).

5‑2. IDE after first run

The IDE is shipped with the most current version of ODRA. However it is possible to update the ODRA library manually by replacing appropriate jars in the “IDE-libs” directory.

5.3 General IDE Information

We found that the big number of jEdit’s options could be confusing for an ODRA developer. Thus, we have hide/removed some of them, for instance, different syntax highlighting. If the programmer needs such functionalities it is possible to restore them (consult the jEdit manual).

Fig.52 shows ODRA-IDE just after a first run. The left panel contains “Project Explorer”, which allows viewing and manipulating workspace (with projects) containing files defining project’s structures. Each item has its own context menu (accessible using a right click). Some options could be called from a few places, i.e. a context menu and the main menu.

The bottom panel contains a few tabs, namely:

·        Messages showing i.e. compilation errors, warning or just information,

·        ODRA CLI (see Fig.53) encapsulates native ODRA Command Line Interface allowing performing most of the ODRA tasks,

5‑3. Part of the ODRA-IDE window presenting ODRA CLI

·        ODRA Query (Fig.54) is dedicated to write queries send to the ODRA server. Actually, it works with all SBQL statements, including the imperatives one.

5‑4. Part of the ODRA-IDE window presenting functionality for writing queries

The main part of the ODRA-IDE window occupies the text editor allowing the programmer for writing source code of SBQL programs. When a user clicks a file in the project tree, its content is presented in this window.

jEdit (and of course ODRA-IDE too) has its own window manager, which supports the following operations:

·        minimizing/maximizing is done by clicking on window’s label,

·        docking is accessible using the special menu available “under” the small triangle icon (see Fig.5-2). Available options allow to dock any window at the top, bottom, left or right of the ODRA-IDE main window.

5‑5. Window's GUI menu

·        undocking (floating) is also accessible using the menu.

·        instantiating a new instance.

·        closing – self explaining.

Some of the IDE functions are available using different options, i.e. by clicking an icon on a toolbar or choosing appropriate item from a context menu.

5.4 Working with Projects

Similarly to other IDEs, ODRA IDE supports an unlimited number of projects. The projects are grouped into a workspace which can be seen at the top of the projects’ tree.

5.4.1 Creating a New Project

In order to create a new project, follow the procedure:

5‑6. Creating a new project using workspace's context menu

·        Using right mouse button, activate workspace’s context menu and select Create a new project. The result should be similar to Fig.5‑6.

·        Enter a name for the new project. The name should be unique, however it is not checked by IDE.

·        Select a location for project files. The location is a simply directory in the local file system.

5‑7. Workspace with two projects

Fig.5‑7 shows a part of the workspace tree containing two projects. The first one is also connected to an ODRA server (see next sub chapters).

Notice that the name of the first project is bolded. It means that this is a default project. All project commands which will be executed without a proper context, will be related to the default one. It is also possible to switch from one default project to another (using an appropriate context menu).

An ODRA project contains an ODRA server and files (SBQL, XML, TXT).

5.4.2 Files in a project

As mentioned before, an ODRA IDE project contains files. There are two possibilities:

·        creating a new file in the project’s directory. Select Create a new file from project’s context menu. Then enter the file name. A new file will be created and placed in the project’s directory.

·        “importing” an existing file into a project. Select “Add an existing file” from project’s context menu. Then select a file(s). Notice that it is possible to import many files using the shift key. Selected file(s) will be added to the project’s structure, but will not be copied to the project’s directory.

5‑8. ODRA IDE after importing two sample files

Fig.58 shows an IDE window after importing two sample files located in “_SampleFiles” directory of the ODRA-IDE distribution.

A file’s context menu allows for opening the file in the IDE editor. The same result could be achieved using double click. It is also possible to remove a file from a project (see Fig.59).

5‑9. File’s context menu

5.4.3 Saving/Loading workspace

The entire workspace could be saved to a file. Actually information about the workspace is saved rather than the workspace content. That means that not all of the project files are stored in the workspace file. Thus, in case of backuping data, all projects files and workspace information must be stored in a safe place.

Saving or loading a workspace is accessible from a workspace context menu. The programmer has to select Save Workspace or Load Workspace from the workspace context menu.

Notice that currently a workspace records the information on projects and its files as absolute (not relative) paths. This approach will be probably changed in the future (because of problems with moving projects or their parts).

5.5 Working with an ODRA Server

ODRA IDE works in the client-server architecture. Thus, the client (IDE) should be connected to an ODRA server. There are two options:

·        starting a default server working as a part of the IDE. If default server has started successfully, its icon in the project’s tree changes the colour into green. If the operation fails, a message will be presented to the user.

·        connecting to an existing ODRA server. A dedicated dialog box will be presented to the user. After entering some information, IDE tries to establish a connection. If the operation will succeed, the server’s icon also turns green.

5‑10. “Connect to a server” dialog

In both cases, the success of an operation could be verified by checking if the server’s sub node contains the Module section. After expanding the node, it is possible to peek the server’s content.

One of the easiest way of feeding a server with data is using one of the import plugins. Currently there are two importers:

·        XMLImporter,

·        XSDImporter.

Next sub sections describe them from the IDE point of view. More information about importers could be found in Chapter 11.

5.5.1 XML Importer

XML importer reads an XML file and load its content on the server. However notice that an XML file does not have information required by the ODRA’s type checking features. Thus, usability of a plain XML importer is limited, because previously it is necessary to define all types of the resulting ODRA objects. A better approach uses the XSD importer (see chapter 5.5.2), which automatically imports all the types necessary to import an XML file.

The procedure of importing an XML file is as follows:

·        Create a new project,

·        Run a default server or connect to an existing one,

·        Form a server’s context menu, using the right mouse button, select “Import data using plugin”. As a result, a dedicated dialog will be shown (see Fig.511),

5‑11. Dialog for importing data

·        Choose a plugin “XMLImporter” (make sure it is not “XSDImporter”),

·        Select an existing XML file. For testing purposes it is possible to chose a sample file shipped with ODRA IDE: “_SampleFiles\XML\bookstore.xml”,

·        Select an existing module on the server (e.g. “admin”). An imported data will be placed “inside” the selected module.

·        Enter necessary parameters. The number and types of the parameters depend on a particular importer (consult the importer’s manual).

Depending on the file size and speed of network connection, the import of a process could take a while. If importing will finish successfully, appropriate message will be shown.

5‑12. Sample project's tree after importing bookstore data

Note that, in case of the sample file, a new Data section (“bookstore”) has been created under the module admin (see Fig.512).

When a data has been successfully imported, it is also possible to execute a query running on the data i.e.: bookstore;. However, queries work only if the metadata is available (not a case in importing plain XML file) or type checking is switched off (default behaviour for type checking is on).

5.5.2 XSD Importer

As mentioned in the previous chapter, the better way of importing XML data into the ODRA server, is utilizing XSD importer rather then XML importer.

The procedure of importing an XML data using XSD importer consists of two steps:

·        importing metadata located in an XSD file,

·        importing real data from an XML file.

Both of them are very similar to the procedure described in case of the XML importer. However to make it really clear, following sample scenario is described:

·        Create a new project,

·        Run a default server or connect to an existing one,

·        Form server’s context menu, using the right mouse button, select “Import data using plugin”. As a result dedicated dialog will be shown (see Fig.511),

·        Choose a plugin “XSDImporter” (make sure it is not “XMLImporter”),

·        Select an existing metadata XSD file, i.e. “_SampleFiles\XML\personnel.xsd”,

·        Select an existing module on a server (e.g. “admin”). An imported metadata will be placed “inside” the selected module.

·        Enter necessary parameters. The number and types of the parameters depend on a particular importer (consult the importer’s manual). As a result metadata from the file has been imported by the server. It can be seen on the project’s tree (Fig.513). This is the end of the procedure’s first step.

5‑13. Server's content after importing metadata

·        At the beginning of the step two, from the server’s context menu, using right mouse button, select “Import data using plugin”. As a result dedicated dialog will be shown (see Fig.511),

·        Choose a plugin “XMLImporter” (make sure it is not “XSDImporter”),

·        Select an existing XML data file, i.e. “_SampleFiles\XML\personnel.xml”,

·        Select an existing module on a server (e.g. “admin”). An imported metadata will be placed “inside” the selected module.

·        Enter parameter: “useMetabase”. The number and types of other parameters depend on a particular importer (consult the importer’s manual).

5‑14. Server's content after importing metadata and data

The Fig.514 presents the server’s content after importing metadata and data.

Because both data and metadata has been imported, it is possible to send a query running on imported data. Fig.515 contains partial result of a query personnel; visualized in IDE.

5‑15. Partial result of the query visualized in the ODRA IDE

5.5.3 Viewing database server content

Sometimes it is necessary to see a server’s content taking into account internal data structures. It is especially useful for debugging of SBQL queries and programs. ODRA IDE has a dedicated functionality which currently utilizes a simple textual form. The functionality is available using the server’s context menu: “DEBUG: Dump store”. The result of the operation is shown on Fig.516.

5‑16. Server's content using Dump Store functionality

5.5.4 Showing modules content.

An ODRA server node in the project tree contains a very important sub-node called “Modules”. The entire server content is “attached below” this special node. Using an appropriate context menu it is possible to refresh the visualization of the server’s content in IDE (see Fig.517).

5‑17. Special node "Modules" and its context menu

Due to the performance reason, it is sometimes necessary to manually call Reload option from the context menu.

5.5.5 Showing a server data value

Node “Modules” contains the entire server content: modules and data. Each data item could be examined by presenting its value. Dedicated context menu has two options:

·        Show value in the internal mode,

·        Show value in the user-friendly mode.

The first option (Fig.518-b) is useful if we would like to know the internal (server) structure of the data. The latter (Fig.518-a) is better if we are interested just in the value not in its build. Notice that the internal data structure is much more complicated (almost unreadable) then the processed user friendly mode.

5‑18. Two kinds of data visualizations

5.5.6 Showing server's memory monitor

ODRA IDE allows monitoring of the server’s RAM memory consumption (see Fig.519). Actually it is the memory consumed by the Java Virtual Machine (JVM) running the ODRA server. The monitor is started using the server’s context menu: Show memory monitor. There is also a possibility to run the Java garbage collector (from within the monitor).

5‑19. Server's memory monitor

5.5.7 Showing server's memory utilization

Another administration functionality (also accessible using the server’s context menu) is presenting the structure of the ODRA server persistent store. Fig.520 shows it in action.

5‑20. Visualization of the ODRA persistent store

5.6 Compiling and Running

5.6.1 Building a project

Building a project is a process when each file in the project is send to the server and compiled. Thus, before the compilation, the project should be connected to a server.

In order to build a project, select “Build” from the project’s context menu. If the project’s server is not running, the default one will be started. After the compilation, there will be some messages in the “Messages” panel (bottom of the screen). If there will be errors/warnings, you can open appropriate file by clicking error description. Note then a line with an error is highlighted. Try to compile sample files and introduce some errors to see what will happen.

The following procedures shows how to compile sample files:

·        Start a new project (see subchapter 5.4.1),

·        Connect to an existing server or start a default one (see subchapter 5.5),

·        Add sample files to the project according to the procedure described in sub chapter 5.4.2.

·        Click a button Build default project (upper right part of the window) or select Build from the project’s context menu.

5‑21. ODRA IDE after compiling sample project

As a result all project files have been send to the server and compiled. Notice (see Fig.521):

·        A message inside the Messages tab,

·        Two new modules (data, procedures) have been created on the server (under the module Admin),

·        Data x has the initial value 0. The value has been put under the node data: x after selecting a dedicated command (see sub chapter 5.5.5).

Edit the sample files, trying to test IDE’s reaction for errors. Fig.522 presents error message after introducing some syntax errors to the sample file. Notice that a line with an error is highlighted with red. It is also possible to double click specified error message and directly jump to the line.

5‑22. ODRA IDE presenting a compilation error

5.6.2 Running a project

Currently ODRA programs do not have an equivalent of the regular programs main method. Such an approach allows running any method or query as an SBQL program. ODRA IDE has a dedicated functionality which supports a similar option. Follow the procedure:

·        Start a new project (see subchapter 5.4.1),

·        Connect to an existing server or start a default one (see subchapter 5.5),

·        Do one of the following:

o       select “Debug” from project’s context menu (Fig.523a),

o       select “Execute a query” from server’s context menu (Fig.523b),

o       click a button (presenting a running man) at the top right area of the ODRA window (Fig.523c).

5‑23. Different ways of running queries

·        Every of the above actions will occur in showing the same querying tab (Fig.524),

5‑24. ODRA querying tab

·         The querying tab consist of the following elements:

o       Module combo box allows selecting a module where the query will executed. Sometimes it is necessary to hit Reload button to refresh the list.

o       Query text box allows for writing queries (including multiple lines). Clicking on the Execute button will send the query to a server and execute it.

o       Checkbox specifying an output mode.

o       The result tree contains the answer from a server. Using the dedicated context menu (see Fig.525) it is possible to:

§       copy the result to a clipboard in two different text format (text-like, XML-like),

§       expand the entire tree. It is especially useful if the tree is complicated.

5‑25. Using query result’s context menu

Just to make sure that everything is clear, work out the following example:

·        Import XSD metadata and XML data (see subchapter 5.5.2)

·        Enter (or select from the combo box) the module name “admin”,

·        Enter a query code (method name): personnel; This query will return all persons working as a personnel, which is shown on Fig.526.

5‑26. Sample query result

·        Alternatively it is possible to write

o        “admin.procedures” as a module name,

o       proc(); as a procedure name (query code). Those information could be utilized in case of sample files (see subchapter 5.6.1).

Of course we advise to try many different queries including mathematical calculations (e.g. 2+2 is a valid SBQL query). More sample queries could be found in other parts of this document.

5.7 ODRA IDE CLI (Command Line Interface).

The ODRA Command Line Interface (ODRA CLI) is a basic way of interacting with an ODRA server. ODRA IDE CLI tab (Fig.527) just encapsulates the original ODRA CLI with some improvements.

5‑27. ODRA IDE CLI after executing help command

At the top of the ODRA IDE CLI tab there are four buttons:

·        Clear input clears all entered commands.

·        Clear output clears all responses received from a sever.

·        Connect makes easier connecting to the project’s server.

·        CLI Variables helps setting and reading various CLI variables. Just select one of the possible states (Fig.528). Keep in mind that the variables are linked with the CLI (not the IDE or a server). Another way of interacting with the variables is using workspace’s menu.

5‑28. Support for CLI variables in the ODRA IDE

For a list of available CLI commands, just type "help" in the input filed. Please notice that it is possible to resize Input and Output sections (using standard “drag” behaviour).

5.8 More Samples

Full description of the ODRA IDE for Java programmers is the subject of another document,  ODRA-IDE API Specification.doc. The specification allows to use, extend and customize the ODRA-IDE using a dedicated Java API.

 

 

Last modified: July 9, 2008