Qizx Studio Help

Version 4.4

Dec 24, 2011

Abstract

Online help of Qizx Studio and Qizx Admin, user interfaces for Qizx.


Table of Contents

1. Starting Qizx Studio
2. The 'XML Libraries' tab
2.1. Library browser
2.2. Metadata Properties view
2.3. Document display
2.3.1. Export document to file
2.3.2. View mode
3. The 'XQuery' tab
3.1. XQuery Editor
3.1.1. Query Execution
3.1.2. Stopping Query execution
3.1.3. Clear editor text
3.2. Result View
3.2.1. Move forward and backward in result sequence
3.2.2. Export result sequence to a file
3.2.3. Change the display style of results
3.3. Message View
4. The 'Admin' Tab
4.1. Configuration tab
4.2. Maintenance Tasks tab
4.2.1. Running tasks
4.2.2. Past tasks
4.2.3. Manual Operations
4.2.4. Scheduled Full Backup
4.2.5. Scheduled Incremental Backup
4.2.6. Scheduled Optimize
4.3. Statistics tab
4.4. Running Queries tab
5. Dialogs
5.1. Open local Library Group dialog
5.2. Connect to Server dialog
5.3. 'XML Catalogs' dialog
5.4. 'Create Collection' dialog
5.5. 'Import Documents' dialog
5.6. 'Import non-XML Documents' dialog
5.7. 'Export Document' dialog
5.8. Metadata Property Editor dialog
5.9. 'Change Indexing Specification' dialog
5.9.1. Reindexing Dialog
5.9.2. Optimize Library Dialog
5.10. 'Backup Library' dialog
5.11. 'Error Log' dialog

Qizx Studio is a graphic user interface built on top of the API provided by the Qizx XML indexing and query engine.

Qizx Studio has several purposes:

This documentation assumes that you have at least basic notions about XQuery and Qizx (XML Library, Collection, Document).

1. Starting Qizx Studio

Qizx Studio can be started:

  • From a graphic environment

  • From the command line: it supports a few option switches similar to the command-line too qizx. Here are the main ones:

    -group path, -g path

    Specifies the location of a group of XML Libraries - or the address of a remote server.

    • Local Library group on disk: the path points to the root directory of the Group.

    • Server: the path is an HTTP URL like http://somehost:8080/qizx/api.

      A default installation of a Qizx Server would end with "/qizx/api" which corresponds to the Qizx REST API connector. But this path - of course the host and the port too - depend on the configuration of the server. See the Server installation documentation for more details.

    -login username:password

    Used when connecting to a Qizx server that requires authentication. Since the password may appear on the command-line, this is not recommended for the best security. You may want to use the following switch -auth:

    -auth secret-file

    Specify login credentials read from a file for better security. If authentication is required, credentials will be read from this file. The file should contain the following values:

    login=admin                                                                                           
    password=xxxx

    Of course the file should be protected from reading by other users.

2. The 'XML Libraries' tab

This tab is used to manage XML Libraries: creation, browsing, maintenance.

Note

In Qizx/open, this tab is absent.

It is divided in three views:

  1. Library Browser (left side): a tree view to browse XML Libraries and contained Collections

  2. Metadata Properties view (top right): displays the properties of a selected Document or Collection

  3. Contents of Document view (bottom right): displays the contents of a selected XML Document.

Figure 1. XML Libraries tab

XML Libraries tab

2.1. Library browser

This view displays the contents of a XML Library Group as a tree.

The view displays the following objects:

  • XML Library Group : the currently opened group of Libraries.

  • XML Library : a library belonging to the group

  • Collection : a Collection inside a Library. May contain other collections.

  • Document : a well-formed XML document stored and indexed in a Collection.

Each kind of object has an associated right-click menu, which gives access to a number of operations:

  • XML Library Group right-click menu:

    • Open Library Group: opens a group of XML Libraries located in a directory. A file chooser appears to select that directory.

      In this mode, Qizx Studio has exclusive access to the XML Libraries. If another application or server already has locked the Libraries, an error panel will appear.

      This command also allows opening a single XML Library by selecting its root directory: It is a special case where the Library Group has no defined location, and therefore creating other libraries is not possible.

    • Connect to Server: opens a client connection to a Qizx Server.

      This will likely present an authentication dialog asking for a user name and a password (depending on the configuration of the server).

    • Close Library Group: closes the current group of Libraries. If currently connected to

      Passes in a mode where no Library is available. Note that it is still possible to run XQuery expressions, as long as they don't perform queries on a Library. This is equivalent to using Qizx/open.

    • Create Library Group: creates a group of Libraries in a directory. This directory is first selected by a file chooser. It must be empty or non-existent. The Library Group is created in the directory, then a dialog asks for the name of the first Library to be created inside the group.

    • Create Library: allows creating more XML Libraries inside the current group.

  • XML Library right-click menu:

    • Import Documents: to store XML documents into the selected Library (in the root Collection); see the Import Documents dialog.

    • Use Library as Query domain: query domain means the default root of a XQuery/XPath path expression. For example, assume that you have a Library containing the plays of Shakespeare (as marked up by Jon Bosak), that you select the Library as the query domain, then the query //SCENE will return all SCENE elements in the Library. Note the particular query //SCENE has no explicit root or start-point. It uses here the default query domain.

      This feature is not supported in client-server mode (because it does not make much sense).

    • Indexing: a sub-menu that deals with indexing specifications.

      • Indexing Specification: load a new specification written in XML. See details here.

      • Rebuild all indexes: this operation is normally required after changing the indexing specifications.

      • Optimize Library: this a compaction operation that can slightly improve the performance of queries on the Library. It is normally performed automatically after a certain number of transactions.

    • Backup Library: this command makes a backup copy of a Library to an external directory.

    • Delete Library: this command physically destroys the selected Library.

    • Refresh: useful in client mode to see the latest state of the Library: another client may have modified it.

      Notice there is currently no notification mechanism that would allow an automatic refresh on update of an XML Library.

  • Collection right-click menu:

    • Use as Query domain: query domain means the default root of a XQuery/XPath path expression (See here for more details). If a Collection is used as query domain, the query is restricted to all documents contained within the Collection at any level.

    • Import Documents: command used to store XML documents into the Collection. Invokes the Import Documents dialog.

    • Create Sub-Collection: asks for the name of a Collection which will be child of the selected collection..

    • Copy Collection: this command allows copying the selected Collection and all its contents (sub-collections and documents) to another location in the same Library.

    • Rename Collection: this command allows changing the name or the location of the collection.

    • Delete Collection: this command destroys the selected Collection and all its contents (sub-collections and documents).

    • Refresh: useful in client mode to see the latest state of the Collection: another client may have modified it.

  • Document right-click menu:

    • Use as Query domain: query domain means the default root of a XQuery/XPath path expression (See here for more details). If a Document is used as query domain, the query is restricted to this particular document. For example if the query domain is the document /coll/doc1.xml, the query //TITLE is equivalent to doc("/coll/doc1.xml")//TITLE.

    • Export Document: command used to extract the XML contents of the document into a local file. Invokes the Export Document dialog which allows choosing serialization options.

    • Copy Document: this command allows copying the selected Document to another location in the same Library.

    • Rename Document: this command allows changing the name or the location of the document.

    • Delete Document: this command destroys the selected Document.

    • Refresh: useful in client mode to see the latest state of the document: another client may have modified it.

2.2. Metadata Properties view

This view displays the properties (also called metadata) of the currently selected Library member, i.e Document or Collection.

The name (in blue) and the value of the property are displayed.

Modifying properties

By right-clicking on a property, its value and type can be edited.

Note: though the 'path' property can be edited, it is in fact built-in and will not change. It can be changed through the 'Rename' operation, by right-clicking on the corresponding Collection or Document.

2.3. Document display

This view displays the XML contents of a selected document. It should be empty if no document is selected.

2.3.1. Export document to file

With the button , you can save the document to a file. This invokes the Document Export Dialog.

2.3.2. View mode

This drop-down selector selects one of two display modes for a XML Data Model (i.e the contents of a document):

  • Markup: this is a XML-like display

  • Data Model: shows each individual node constituting the data model.

3. The 'XQuery' tab

This tab is used to edit and execute XQuery queries.

It is divided in three views:

  1. Query editor (top left): a text editor with execution button and query history.

  2. Messages view (bottom left): displays compilation and execution messages.

  3. Query Results (right): displays the items of the result sequence.

Figure 2. XQuery tab

XQuery tab

3.1. XQuery Editor

This area is a basic text editor of XQuery source code, performing syntax coloring.

A file can be loaded in the editor through the menu FileOpen XQuery, and conversely the source code can be saved with menu FileSave XQuery.

Specifying the path of a XQuery source file in the command-line of Qizx Studio will automatically load the file. This happens if the file extension (in principle .xq) has been associated with the Qizx Studio application, depending on the Operating System used.

The editor has several buttons and controls in the tool-bar above:

3.1.1. Query Execution

The button Execute compiles the current query and evaluates it. During execution the button changes to Stop.

The result sequence is displayed in the Result View. A message in the Message View below tells the number of items in the result sequence, and the time in milliseconds taken by the evaluation.

3.1.2. Stopping Query execution

A lengthy evaluation can be canceled with the button Stop . No results are displayed.

3.1.3. Clear editor text

The button clears the editor, to type a new expression.

3.2. Result View

This view displays the result sequence produced by the evaluation of a XQuery expression.

  • Simple items (integer, string, etc) are displayed with their type.

  • Node items are displayed either in "markup" style, looking like XML.

Results are displayed by pages of 100 items. A set of buttons can be used to traverse the result sequence if it is long.

Figure 3. XQuery tab with miscellaneous results

XQuery tab with miscellaneous results

3.2.1. Move forward and backward in result sequence

The two vertical arrows move the position of the displayed page by 100 items forward or backward.

3.2.2. Export result sequence to a file

This button saves the whole result sequence onto a file.

Note that the resulting file will not in general represent a well-formed XML document, unless the result sequence contains a single Node. A message signals when the result is not well-formed.

The invoked dialog allows choosing serialization options. Some of these options (HTML) do not always make sense, depending on the actual results.

Figure 4. Export results dialog

Export results dialog

3.2.3. Change the display style of results

This command changes the display style for Nodes only.

  • The Markup style mimics XML markup.

  • The Data Model style is a tree view of Node structures.

3.3. Message View

This view displays compilation and execution messages.

When an error is displayed, the location is underlined: by clicking on it, the cursor of the Query Editor is placed on the error location.

4. The 'Admin' Tab

This tab is visible only in Qizx Admin, a variant of Qizx Studio devoted to Administrator tasks.

It contains 4 sub-windows accessed by tabs:

  1. Configuration: displays and edits Configuration properties, for a Qizx Server (remote mode) or a local XML Library group.

  2. Maintenance Tasks: manages tasks like backups and index optimizations.

  3. Statistics: displays run-time statistics about Qizx Server or a local XML Library group.

  4. Running Queries: displays XQuery script currently executing, and allows cancelling a query that takes too much time.

Refresh:

The tabs contain a Refresh button to redisplay the current state.

Some have an auto-refresh selector allowing refresh at regular intervals.

4.1. Configuration tab

This tab displays the current values of Configuration properties.

The Value fields can be edited: modified values are marked by a colored background. The Save button must then be used to save the values back to the server or Database group.

The right-click menu can be used to restore the default value of a property.

4.2. Maintenance Tasks tab

This tab displays Maintenance Tasks such as backups, re-indexing, and index optimizations.

It also allows specifying scheduled tasks at regular intervals.

It shows a table of active tasks, a table of past tasks, and several forms for manual or scheduled operations.

4.2.1. Running tasks

This table displays the currently running backup, reindexing or optimization tasks.

The auto-refresh selector allows refreshing at regular intervals.

4.2.2. Past tasks

This table displays the tasks executed during the most recent period.

A drop-down selector allows choosing the displayed period: 1 day, 2 days, 1 week, 1 month.

4.2.3. Manual Operations

A form to run an operation for a particular XML Library.

  • XML Library selector: drop-down menu to choose the XML Library if there are several..

  • Backup button: a file selection field on the right allows defining the directory where to do the backup.

    From version 4.4, an incremental backup can be selected.

  • Reindex button, to completely reindex the database

  • Optimize button, to run a database optimization.

4.2.4. Scheduled Full Backup

A form to define a regularly scheduled backup for all XML Libraries: for example once a day (the default).

This form is simply an editor for configuration properties named scheduled_backup_* . After modification, the Save button on the right must be used.

  • Interval: once a day, once an hour etc

  • Time: precise time to run the operation.

    Note that if the interval is greater than 1 day, it is possible to specify the day, for example:

    sunday 03:

  • Directory: the place on the server's file-system where the XML Libraries are saved.

    See hereafter for details.

  • Number of directories: the backup can be done alternately on several directories.

    If this value is greater than 1, the directory path above is appended with values 0, 1, 2... cyclically.

    For example if the directory is /backups/dbs/ and Number of directories is 3, the backup of library mydb will be done cyclically on /backups/dbs/mydb0, /backups/dbs/mydb1 and /backups/dbs/mydb2.

4.2.5. Scheduled Incremental Backup

A form to define a regularly scheduled incremental backup for all XML Libraries: for example once an hour (the default).

This form is simply an editor for configuration properties named scheduled_ibackup_* . After modification, the Save button on the right must be used.

  • Interval: once an hour, once a day, etc

  • Time: precise time to run the operation.

    Note that if the interval is one hour, only the minutes are used.

  • Directory: the place on the server's file-system where the XML Libraries are saved.

    See hereafter for details.

4.2.6. Scheduled Optimize

A form to define a regularly scheduled optimization operation for all XML Libraries: for example once a day.

This form is simply an editor for configuration properties named scheduled_optimize_* . After modification, the Save button on the right must be used.

  • Interval: once a day, once an hour etc

  • Time: precise time to run the operation.

    Note that if the interval if greater than 1 day, it is possible to specify the day, for example:

    sunday 03:

  • Max Time: the time spent for the optimize operation can be limited by this value.

4.3. Statistics tab

This tab displays run-time statistics about Qizx Server or a local XML Library group.

An "expert" check-box shows more detailed statistics by breaking-down

4.4. Running Queries tab

This tab displays currently executing XQuery scripts, and allows cancelling a script.

Notice that a query is considered "running" during the initial execute() method and when iterating on the result sequence.

5. Dialogs

Note

In Qizx/open, only the XML Catalogs and Error Log dialogs are available.

5.1. Open local Library Group dialog

Used for opening an XML Library group located on a local disk.

  • File browser: selects a directory on a local file-system.

  • History of recently opened groups: double clicking on this list selects the clicked entry.

5.2. Connect to Server dialog

Used for opening an XML Library group managed by a remote server.

Figure 5. Connect to Server dialog

Connect to Server dialog

  • Field text for the URL of the server:

    this URL is of the form http://host:port/webapp/api, where host, port and webapp depend on the installation.

    The path 'qizx/api' is the default for the REST API of Qizx, but it can be changed in the configuration of the server.

  • History of recently opened groups: double clicking on this list selects the clicked entry.

Authentication

Generally, a server will require a login and password on connection. This is configured in the installation of the server.

Figure 6. Connect to Server authentication dialog

Connect to Server authentication dialog

5.3. 'XML Catalogs' dialog

A dialog used to define XML Catalogs used when documents are imported.

Qizx supports the OASIS XML Catalogs specifications.

The dialog edits the value of the system property "xml.catalog.files" which can contain a semicolon-separated list of catalog files.

It is possible to add file paths and URLs to the list.

5.4. 'Create Collection' dialog

This dialog allows creating a child Collection of the selected Collection.

It simply prompts for the name of a child collection. This name must not contain the slash '/' character.

5.5. 'Import Documents' dialog

This dialog allows parsing, storing and indexing one or several XML documents into a Collection inside a XML Library.

Figure 7. Import dialog

Import dialog

An import operation is performed in two steps:

  1. Create an import list of XML files or of directories. This list displays the path, the number of files (for directories), the total size in bytes, the filter used (for directories).

  2. Push the button "Start Import".

To Add a file or directory (or several) to the list, use the button "Add File/Folder" and select the file(s) or directory.

For directories, you may first want to choose a filter for contained files. a new filter can be typed in the combo-box.

Items can be removed from the list by selecting them and using the button Remove, or the button "Clear all".

DTD and Schema are resolved through XML catalogs. The XML Catalogs menu allows editing the catalogs.

Parsing errors are reported in the Messages area at bottom.

5.6. 'Import non-XML Documents' dialog

This dialog (very similar to Import XML dialog) is used to import non-XML (ie any text or binary file) into a Collection inside a XML Library.

Non-XML Documents are similar to "Blobs" in relational databases. They can only be written and retrieved. There is no indexing and even text files cannot be searched by their contents.

However Non-XML Documents can have metadata properties, just like XML Documents and Collections, and these properties can be searched.

Beware that XML files will be treated like any other file by this tool. Use the XML Document Import dialog to import XML documents.

Figure 8. Import dialog

Import dialog

An import operation is performed in two steps:

  1. Create an import list of files or of directories. This list displays the path, the number of files (for directories), the total size in bytes, the filter used (for directories).

  2. Push the button "Start Import".

To Add a file or directory (or several) to the list, use the button "Add File/Folder" and select the file(s) or directory.

For directories, you may first want to choose a filter for contained files. a new filter can be typed in the combo-box.

Items can be removed from the list by selecting them and using the button Remove, or the button "Clear all".

As this is an import of binary files, there will be no parsing errors.

5.7. 'Export Document' dialog

This dialog is used for extracting a selected Document from a Library and write its contents back to a file.

The dialog allows choosing the file and Serialization options.

It is also used for exporting the results of a XQuery evaluation.

5.8. Metadata Property Editor dialog

This dialog allows adding a new property or editing an existing property. It is invoked by right-clicking on the name of a property.

The value is edited in string form. The type selected with the Type combo-box is then used to parse the value accordingly.

Possible types are currently:

  • String.

  • long integer (xs:integer).

  • double (xs:double).

  • Date (java.util.Date) : a value is edited in ISO standard form, for example 2010-05-01T14:54 .

  • boolean (xs:boolean).

  • node(): a single node (generally an element).

  • expression: any executable XQuery expression can be entered. Only the first item will stored as property value.

5.9. 'Change Indexing Specification' dialog

This dialog allows defining and changing the Indexing Specifications. See Chapter 9, Configuring the indexing process for more information about Indexing Specifications.

There are three ways of modifying the Indexing Specifications:

  • Directly edit basic specifications using the simple editor presented in the dialog. This editor allows editing the most common indexing properties, but is too limited to handle all the Indexing capabilities.

  • Load a specification file (XML format described in the documentation), using the button Load From File...

  • Reset Indexing specifications to the default value (button "Restore To Default").

After any change (when using the button Apply), the user is suggested to rebuild the indexes entirely. This is strongly recommended for avoidance of inconsistencies in query results.

5.9.1. Reindexing Dialog

This is a simple dialog through which the indexes can be rebuilt entirely, using the current Indexing Specifications.

It is invoked automatically after a change in the Indexing Specification Dialog.

Please note that since Qizx 2.1, re-indexing is a synchronous operation. A progress bar is displayed by the dialog.

5.9.2. Optimize Library Dialog

This is a simple dialog through which the XML Library can be put into an "optimal" state. This operation involves compacting the document storage and the indexes, if necessary.

Please note that since Qizx 2.1, optimizing a Library is a synchronous operation. A progress bar is displayed by the dialog.

5.10. 'Backup Library' dialog

This dialog prompts you for a directory in the file system where the Library will be saved. The directory contents will be erased before backup.

This is a ``hot backup'' which saves a snapshot of the database: any modification made by another connection during the backup will be ignored. This is meaningful and useful in a multi-user environment, like a Web Application running in a servlet container.

The Restore operation consists simply of moving or copying the directory of the backup Library to the place of the original Library (see Administrator section of the manual for details).

Figure 9. Backup dialog

Backup dialog

5.11. 'Error Log' dialog

This non-modal dialog appears when an error or warning must be displayed.

Typically it appears if you try to use a XML Library that is already locked by another instance of the Qizx engine (an instance of Qizx Studio, of the qizx command-line tool, or one of your applications).