Qizx Studio Help
Prev | Part V. Tools |

## Qizx Studio Help

### XF

XMLmind

Web: http://www.xmlmind.com/qizx/
Email: `<qizx-support@xmlmind.com>`

Version 4.0

Copyright © 2007-2010 Axyana Software

May 10, 2010

Abstract

Online help of Qizx Studio, a graphic user interface for Qizx.

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:

- Offer an interactive tool to edit, execute and debug XQuery queries (there is no debugger yet, but that is planned for a future version such as 4.1 or 4.2).

- Offer an easy-to-use interface for administering XML Libraries.

- Demonstrate most of Qizx functionalities through menus and dialogs.

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

### 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

### 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 File → Open XQuery, and conversely the source code can be saved with menu File → Save XQuery.

### Caution

No check is performed when saving or when exiting the application, however the query history (see below) keeps trace of all queries entered.

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

#### 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

#### 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. Dialogs

### Note

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

### 4.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.

### 4.2. Connect to Server dialog

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

Figure 5. 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

### 4.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.

### 4.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.

### 4.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

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.

### 4.6. '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.

### 4.7. 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.

### 4.8. 'Change Indexing Specification' dialog

This dialog allows defining and changing the Indexing Specifications. See ??? 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.

#### 4.8.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.

#### 4.8.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.

### 4.9. '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 8. Backup dialog

### 4.10. 'Error Log' dialog

This non-modal dialog appears when a serious error is detected by the Library manager.

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).

Prev | Up |
qizx | Home |