Version 4.4
Copyright © 2007-2011 Axyana Software
Dec 24, 2011
Table of Contents
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.
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).
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.
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:
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.
This tab is used to manage XML Libraries: creation, browsing, maintenance.
In Qizx/open, this tab is absent.
It is divided in three views:
Library Browser (left side): a tree view to browse XML Libraries and contained Collections
Metadata Properties view (top right): displays the properties of a selected Document or Collection
Contents of Document view (bottom right): displays the contents of a selected XML Document.
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.
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.
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.
This view displays the XML contents of a selected document. It should be empty if no document is selected.
With the button , you can save the document to a file. This invokes the Document Export Dialog.
This tab is used to edit and execute XQuery queries.
It is divided in three views:
Query editor (top left): a text editor with execution button and query history.
Messages view (bottom left): displays compilation and execution messages.
Query Results (right): displays the items of the result sequence.
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
→ , and conversely the source code can be saved with menu → .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:
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.
A lengthy evaluation can be canceled with the button Stop . No results are displayed.
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.
The two vertical arrows move the position of the displayed page by 100 items forward or backward.
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.
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:
Configuration: displays and edits Configuration properties, for a Qizx Server (remote mode) or a local XML Library group.
Maintenance Tasks: manages tasks like backups and index optimizations.
Statistics: displays run-time statistics about Qizx Server or a local XML Library group.
Running Queries: displays XQuery script currently executing, and allows cancelling a query that takes too much time.
The tabs contain a
button to redisplay the current state.Some have an
selector allowing refresh at regular intervals.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.
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.
This table displays the currently running backup, reindexing or optimization tasks.
The
selector allows refreshing at regular intervals.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.
A form to run an operation for a particular XML Library.
: drop-down menu to choose the XML Library if there are several..
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.
button, to completely reindex the database
button, to run a database optimization.
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
.
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.
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.
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
In Qizx/open, only the XML Catalogs and Error Log dialogs are available.
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.
Used for opening an XML Library group managed by a remote server.
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.
Generally, a server will require a login and password on connection. This is configured in the installation of the server.
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.
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.
This dialog allows parsing, storing and indexing one or several XML documents into a Collection inside a XML Library.
An import operation is performed in two steps:
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).
Push the button "
".To Add a file or directory (or several) to the list, use the button "
" 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 "
".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.
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.
An import operation is performed in two steps:
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).
Push the button "
".To Add a file or directory (or several) to the list, use the button "
" 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 "
".As this is an import of binary files, there will be no parsing errors.
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.
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.
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
Reset Indexing specifications to the default value (button "
").After any change (when using the button
), the user is suggested to rebuild the indexes entirely. This is strongly recommended for avoidance of inconsistencies in query results.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.
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.
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).
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).