Difference between revisions of "Integrating oXygen"

From BaseX Documentation
Jump to navigation Jump to search
(Clarified Perform Queries section, referring to oXygen 17.0 and distinguishing between one-time setup and recurring steps)
 
(29 intermediate revisions by 4 users not shown)
Line 1: Line 1:
 
This tutorial is part of the [[Getting Started]] Section.
 
This tutorial is part of the [[Getting Started]] Section.
It describes how to access BaseX from the [http://www.oxygenxml.com oXygen XML Editor].
+
It describes how to access BaseX from the [https://www.oxygenxml.com oXygen XML Editor].
Currently, there are two variants how to use BaseX in oXygen:
+
Currently, there are two alternatives how to use BaseX in oXygen:
  
* Resources in [[databases]] can be opened and modified.
+
* Resources in BaseX [[databases]] can be opened and modified.
* XPath/XQuery expressions can be run by the [[Query|query processor]] of BaseX.<br/><br/>
+
* XPath/XQuery 1.0 expressions can be run by the [[Query|query processor]] of BaseX.
 +
* '''Note:''' BaseX itself is a highly compliant XQuery 3.1 processor. The restriction to XQuery 1.0 arises from the XQJ Interface which is used to establish the connection between oXygen and BaseX. We strongly encourage you to use the [[Graphical_User_Interface#Text_Editor|XML editor]] integrated into the BaseX GUI to edit and query your XML data!<br/><br/>
  
 
=Access Database Resources=
 
=Access Database Resources=
  
===Preparations===  
+
===Preparations===
* First, start the BaseX [[WebDAV]] service.
 
  
===Configuration===
+
# Download one of the [https://basex.org/download BaseX distributions].
# Go to menu ''Options'' → ''Preferences'' → ''Data Sources''
+
# Start BaseX (see [[Startup]]).
# In the Connections panel, click the ''New'' button ({{Code|+}})
+
# Create a BaseX database, if necessary (see [[Databases]]).
# Enter "BaseX-WebDAV" as connection name
+
# Start the BaseX [[WebDAV]] service.
# Select "WebDAV" in the Data Source combo box
 
# Fill in the appropriate connection details. Below, the default values are shown:
 
#* Set the URL to <code><nowiki>http://localhost:8984/webdav</nowiki></code>
 
#* Set the user name to <code>admin</code>
 
#* Set the password to <code>admin</code>
 
# Now press ''OK'', and your Data Source is ready for use
 
  
You can now open single database files as follows:
+
===Configuration===
  
* Choose ''File'' → ''Open URL...''.<br/>
+
# In oXygen, go to menu ''Options'' → ''Preferences'' → ''Data Sources''.
[[File:Webdav-oxygen01.png]]<br/><br/>
+
# In the Connections panel (in the lower half of the screen), click the ''New'' button ({{Code|+}}).
* Enter the corresponding user name and password (if needed), the URL of the BaseX WebDAV Server, and then click "Browse".<br/>
+
# Enter "BaseX WebDAV" as connection name.
[[File:Webdav-oxygen02.png]]
+
# Select "WebDAV (S)FTP" in the Data Source dropdown box.
 +
# Fill in the appropriate connection details as follows:
 +
#* Set the WebDAV/FTP URL to <code><nowiki>http://localhost:8984/webdav</nowiki></code>.
 +
#* Set the user name to <code>admin</code>.
 +
#* Set the password to <code>admin</code>.
 +
#: [[File:Oxygen-WebDAV-1.png]]
 +
# Now press ''OK'', and your Data Source is ready for use.
 +
 
 +
You can then access your database file(s) via the Data Source Explorer: ''Window'' → ''Show View'' → ''Data Source Explorer''.
 +
 
 +
[[File:Oxygen-WebDAV-2.png]]
  
 
=Perform Queries=
 
=Perform Queries=
 +
 
==One-Time Setup==
 
==One-Time Setup==
  
 
===Preparations===
 
===Preparations===
# Download one of the complete [http://basex.org/download BaseX distributions] (ZIP, EXE).
+
 
# Charles Foster's XQJ implementation provides a default (client/server) and a local driver. If you want to use the first flavor, you need to start a [[Startup#BaseX Server|BaseX Server]] instance.
+
# Download one of the complete [https://basex.org/download BaseX distributions] (ZIP, EXE), if necessary.
 +
# Start BaseX (see [[Startup]]). '''Note:''' Charles Foster's XQJ implementation provides a default (client/server) and a local driver. If you want to use the first flavor, you need to start a [[Startup#Server|BaseX Server]] instance.
  
 
===Configure Data Source===
 
===Configure Data Source===
# Start oXygen and select ''Options'' → ''Preferences'' → ''Data Sources''.
+
 
# In the Data Sources section, add a new data source using the ''New'' button ({{Code|+}}).
+
# In oXygen, select ''Options'' → ''Preferences'' → ''Data Sources''.
# Enter "BaseX-XQJ" as Name and select ''XQuery API for Java (XQJ)'' as type.
+
# In the Data Sources panel, add a new data source using the ''New'' button ({{Code|+}}).
# Add the following JAR files above with the ''Add Files'' Button: {{Code|xqj-api-1.0.jar}}, {{Code|xqj2-0.2.0.jar}} and {{Code|basex-xqj-1.3.0.jar}} (the versions of the JAR file may differ). If you add the BaseX library as well {{Code|basex.jar}}, you can also use the local XQJ driver.
+
# Enter "BaseX" as name and select ''XQuery API for Java(XQJ)'' from the ''Type'' dropdown box.
# Under "Driver class", choose the default or the local XQJ driver ({{Code|net.xqj.basex.BaseXXQDataSource}} vs. {{Code|net.xqj.basex.local.BaseXXQDataSource}}).
+
# Add the following JAR files (downloaded in Preparations procedure) with the ''Add Files'' Button. The versions of the JAR files may differ.
 +
#* {{Code|basex/lib/xqj-api-1.0.jar}}
 +
#* {{Code|basex/lib/xqj2-0.2.0.jar}}
 +
#* {{Code|basex/lib/basex-xqj-9.0.jar}}
 +
#* {{Code|basex/BaseX.jar}}, if you want to use BaseX embedded
 +
# Under "Driver class", choose the preferred driver class:
 +
#* Client/server communication: {{Code|net.xqj.basex.BaseXXQDataSource}}
 +
#* Embedded use (standalone): {{Code|net.xqj.basex.local.BaseXXQDataSource}}
 
# Click ''OK''.
 
# Click ''OK''.
  
 
===Configure Connection===
 
===Configure Connection===
# In the Connections section (in the same Preferences dialog from the Configure Data Source procedure), click ''New'' ({{Code|+}}).  
+
 
# Enter "BaseX" as Name and select "BaseX-XQJ" as Data Source.  
+
# In the Connections section (in the lower half of the Data Source dialog), click ''New'' ({{Code|+}}).
# If you use the default driver, enter these values in the Connection Details section:
+
# Enter "BaseX XQJ" as name and select "BaseX" as data source.
 +
# If you use the default driver, enter the following values in the Connection Details section:
 
#* port: {{Code|1984}}
 
#* port: {{Code|1984}}
 
#* serverName: {{Code|localhost}}
 
#* serverName: {{Code|localhost}}
Line 56: Line 70:
  
 
===Configure New Transformation Scenario===
 
===Configure New Transformation Scenario===
 +
 
# Select ''Window'' → ''Show View'' → ''Transformation Scenarios''.
 
# Select ''Window'' → ''Show View'' → ''Transformation Scenarios''.
# Select the ''XQuery transformation'' tree entry, and click {{Code|+}} to add a new scenario.
+
# In the ''Transformation Scenarios'' panel, click {{Code|+}} and select ''XQuery transformation'' in the lower part of the dropdown list.
#:If this entry does not appear in the tree, click {{Code|+}} and select ''XQuery transformation'' in the dropdown list.
+
# Enter a name for your transformation, e.g. "BaseX" like in the screenshot below.
# Enter a Name and an optional XML and XQuery URL (e.g. your query document/file).
+
# Specify an optional XML and XQuery URL.
# Choose "BaseX" as Transformer from the combo box.  
+
#* If you would like to query the BaseX database you connected to via WebDAV, leave the ''XML URL'' field empty. To access your database, you can use the following function from the BaseX [[Database_Module|Database Module]] in your ''XQuery URL'' file:
 +
#: [[File:Oxygen-query-example.png]]
 +
#* If you specify an XML document in the ''XML URL'' field, you can query its content using {{Code|.}} (dot operator) in your ''XQuery URL'' file.
 +
# Choose "BaseX XQJ" as Transformer from the combo box.
 
# Click ''OK'' to complete the scenario configuration.
 
# Click ''OK'' to complete the scenario configuration.
 +
 +
[[File:Oxygen-WebDAV-3.png]]
  
 
==Execute Query==
 
==Execute Query==
After the one-time setup steps are complete, execute a query using the transformation scenario. Start the transformation by clicking the red ''Apply associated scenarios'' button in the Transformation Scenarios window.
 
 
The results should immediately occur in the result panel.
 
  
--[[User:CG|CG]] 14:45, 29 January 2015 (CET)
+
After the one-time setup steps are complete, you can execute your query using the new transformation scenario. Start the transformation by clicking the red Run button (''Apply associated scenarios'') in the Transformation Scenarios window, while your scenario is selected. The results should be immediately displayed in the result panel.

Latest revision as of 16:51, 22 April 2021

This tutorial is part of the Getting Started Section. It describes how to access BaseX from the oXygen XML Editor. Currently, there are two alternatives how to use BaseX in oXygen:

  • Resources in BaseX databases can be opened and modified.
  • XPath/XQuery 1.0 expressions can be run by the query processor of BaseX.
  • Note: BaseX itself is a highly compliant XQuery 3.1 processor. The restriction to XQuery 1.0 arises from the XQJ Interface which is used to establish the connection between oXygen and BaseX. We strongly encourage you to use the XML editor integrated into the BaseX GUI to edit and query your XML data!

Access Database Resources[edit]

Preparations[edit]

  1. Download one of the BaseX distributions.
  2. Start BaseX (see Startup).
  3. Create a BaseX database, if necessary (see Databases).
  4. Start the BaseX WebDAV service.

Configuration[edit]

  1. In oXygen, go to menu OptionsPreferencesData Sources.
  2. In the Connections panel (in the lower half of the screen), click the New button (+).
  3. Enter "BaseX WebDAV" as connection name.
  4. Select "WebDAV (S)FTP" in the Data Source dropdown box.
  5. Fill in the appropriate connection details as follows:
    • Set the WebDAV/FTP URL to http://localhost:8984/webdav.
    • Set the user name to admin.
    • Set the password to admin.
    Oxygen-WebDAV-1.png
  6. Now press OK, and your Data Source is ready for use.

You can then access your database file(s) via the Data Source Explorer: WindowShow ViewData Source Explorer.

Oxygen-WebDAV-2.png

Perform Queries[edit]

One-Time Setup[edit]

Preparations[edit]

  1. Download one of the complete BaseX distributions (ZIP, EXE), if necessary.
  2. Start BaseX (see Startup). Note: Charles Foster's XQJ implementation provides a default (client/server) and a local driver. If you want to use the first flavor, you need to start a BaseX Server instance.

Configure Data Source[edit]

  1. In oXygen, select OptionsPreferencesData Sources.
  2. In the Data Sources panel, add a new data source using the New button (+).
  3. Enter "BaseX" as name and select XQuery API for Java(XQJ) from the Type dropdown box.
  4. Add the following JAR files (downloaded in Preparations procedure) with the Add Files Button. The versions of the JAR files may differ.
    • basex/lib/xqj-api-1.0.jar
    • basex/lib/xqj2-0.2.0.jar
    • basex/lib/basex-xqj-9.0.jar
    • basex/BaseX.jar, if you want to use BaseX embedded
  5. Under "Driver class", choose the preferred driver class:
    • Client/server communication: net.xqj.basex.BaseXXQDataSource
    • Embedded use (standalone): net.xqj.basex.local.BaseXXQDataSource
  6. Click OK.

Configure Connection[edit]

  1. In the Connections section (in the lower half of the Data Source dialog), click New (+).
  2. Enter "BaseX XQJ" as name and select "BaseX" as data source.
  3. If you use the default driver, enter the following values in the Connection Details section:
    • port: 1984
    • serverName: localhost
    • user: admin
    • password: admin
  4. Click OK to complete the connection configuration.
  5. Click OK again to close the Preferences dialog.

Configure New Transformation Scenario[edit]

  1. Select WindowShow ViewTransformation Scenarios.
  2. In the Transformation Scenarios panel, click + and select XQuery transformation in the lower part of the dropdown list.
  3. Enter a name for your transformation, e.g. "BaseX" like in the screenshot below.
  4. Specify an optional XML and XQuery URL.
    • If you would like to query the BaseX database you connected to via WebDAV, leave the XML URL field empty. To access your database, you can use the following function from the BaseX Database Module in your XQuery URL file:
    Oxygen-query-example.png
    • If you specify an XML document in the XML URL field, you can query its content using . (dot operator) in your XQuery URL file.
  5. Choose "BaseX XQJ" as Transformer from the combo box.
  6. Click OK to complete the scenario configuration.

Oxygen-WebDAV-3.png

Execute Query[edit]

After the one-time setup steps are complete, you can execute your query using the new transformation scenario. Start the transformation by clicking the red Run button (Apply associated scenarios) in the Transformation Scenarios window, while your scenario is selected. The results should be immediately displayed in the result panel.