Integrating IntelliJ IDEA

From BaseX Documentation

(Difference between revisions)
Jump to: navigation, search
 
(19 intermediate revisions not shown)
Line 2: Line 2:
* The [https://plugins.jetbrains.com/plugin/8612-xquery-intellij-plugin xquery-intellij-plugin] by Reece H. Dunn.
* The [https://plugins.jetbrains.com/plugin/8612-xquery-intellij-plugin xquery-intellij-plugin] by Reece H. Dunn.
-
* The [https://plugins.jetbrains.com/plugin/9757-xquery-support--marklogic-debugger XQuery Support + MarkLogic Debugger] plugin by Grzegorz Ligas.
+
* The [https://plugins.jetbrains.com/plugin/7262-xquery-support XQuery Support] plugin by Grzegorz Ligas.
 +
* Both plugins offer support for XQuery 3.1 and can be run as a client or standalone instance. Please note that the two plugins are mutually exclusive and cannot be activated at the same time in IntelliJ.  
* '''Note:''' BaseX itself is a highly compliant XQuery 3.1 processor. 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/>
* '''Note:''' BaseX itself is a highly compliant XQuery 3.1 processor. 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/>
Line 16: Line 17:
=xquery-intellij-plugin=
=xquery-intellij-plugin=
-
This section focuses on Reece H. Dunn's [https://plugins.jetbrains.com/plugin/8612-xquery-intellij-plugin xquery-intellij-plugin].  
+
This section focuses on Reece H. Dunn's [https://plugins.jetbrains.com/plugin/8612-xquery-intellij-plugin xquery-intellij-plugin].
==Installation==
==Installation==
After installing IntelliJ IDEA and BaseX, install the xquery-intellij-plugin by one of the following methods:
After installing IntelliJ IDEA and BaseX, install the xquery-intellij-plugin by one of the following methods:
-
===From the Start Screen===
+
 
 +
'''From the Start Screen'''
 +
 
 +
[[File:intellij-startbildschirm.png]]
 +
 
* Start IntelliJ IDEA and select ''Configure''→''Plugins''.
* Start IntelliJ IDEA and select ''Configure''→''Plugins''.
* In the Plugins window, select the tab ''Marketplace''.
* In the Plugins window, select the tab ''Marketplace''.
Line 28: Line 33:
* You will be prompted to restart IDEA to load the new plugin.
* You will be prompted to restart IDEA to load the new plugin.
-
===From the IntelliJ IDEA Menu===
+
'''From the IntelliJ IDEA Menu'''
* Select ''Settings'' (Windows)/''Preferences'' (macOS) in the ''IntelliJ IDEA'' menu.
* Select ''Settings'' (Windows)/''Preferences'' (macOS) in the ''IntelliJ IDEA'' menu.
* In the Settings/Preferences window, select ''Plugins''.
* In the Settings/Preferences window, select ''Plugins''.
Line 49: Line 54:
==Querying Your Data==
==Querying Your Data==
 +
 +
'''Create a New Project'''
* To create a new project choose the ''Create new project'' option from the start screen or select ''New''→''Project...'' from the ''File'' menu.
* To create a new project choose the ''Create new project'' option from the start screen or select ''New''→''Project...'' from the ''File'' menu.
* In the ''New Project'' dialog, choose ''Empty Project'' from the left-hand column and click the ''Next'' button.
* In the ''New Project'' dialog, choose ''Empty Project'' from the left-hand column and click the ''Next'' button.
-
* Enter a name and location for your project.
+
* Enter a name and location for your project and click on the ''Finish'' button.
 +
 
 +
'''Customize the XQuery Module'''
* Click the ''Add Configuration'' button below the IntelliJ IDEA menu bar.
* Click the ''Add Configuration'' button below the IntelliJ IDEA menu bar.
[[File:Intellij-add-configuration.png]]
[[File:Intellij-add-configuration.png]]
Line 58: Line 67:
* In the ''Manage Query Processors'' dialog, click on the {{Code|+}} button.
* In the ''Manage Query Processors'' dialog, click on the {{Code|+}} button.
* In the ''New Query Processor Instance'' dialog, set the following preferences:
* In the ''New Query Processor Instance'' dialog, set the following preferences:
-
** <code>Name = BaseX</code>
+
** <code>Name = BaseX</code> (optional; if you leave this field blank, <code>[Implementation] [Version]</code> will be used as name)
** <code>Implementation = BaseX</code> (should be preset!)
** <code>Implementation = BaseX</code> (should be preset!)
-
** <code>JAR File = basex/BaseX.jar</code>
+
** <code>JAR File = BaseX.jar</code> (name and location of the JAR file may differ depending on your BaseX distribution and version)
** <code>Hostname = localhost</code>
** <code>Hostname = localhost</code>
** <code>Database port = 1984</code>
** <code>Database port = 1984</code>
Line 68: Line 77:
[[File:Intellij-new-query-processor.png]]
[[File:Intellij-new-query-processor.png]]
* Click ''OK'' to exit the ''New Query Processor Instance'' dialog.
* Click ''OK'' to exit the ''New Query Processor Instance'' dialog.
-
* In the ''Manage Query Processors'' dialog, now choose the "BaseX 9.1.1 (BaseX)" entry and click ''OK''.
+
* In the ''Manage Query Processors'' dialog, now choose the "BaseX [''Version''] (BaseX)" entry and click ''OK''.
-
* The ''Query Processor'' dropdown box in the ''Run/Debug Configurations'' dialog should now also display "BaseX 9.1.1 (BaseX)". If not, select it from the dropdown box.
+
* The ''Query Processor'' dropdown box in the ''Run/Debug Configurations'' dialog should now also display "BaseX [''Version''] (BaseX)". If not, select it from the dropdown box.
* Click ''Apply'' and then ''OK'' to close the ''Run/Debug Configurations'' dialog.
* Click ''Apply'' and then ''OK'' to close the ''Run/Debug Configurations'' dialog.
 +
 +
'''Create a Query File'''
* In the project view, create a new XQuery file, either by right-clicking on the project name and choosing ''New''→''File'' or by selecting ''New''→''File'' from the File menu. Enter a file name and click ''OK''.
* In the project view, create a new XQuery file, either by right-clicking on the project name and choosing ''New''→''File'' or by selecting ''New''→''File'' from the File menu. Enter a file name and click ''OK''.
-
* Type in your query.
+
* Type in your query, e.g. <code>db:open("factbook")</code>, and save your file.
 +
 
 +
'''Create a New Configuration'''
* Click on the ''Add Configuration'' button once again.
* Click on the ''Add Configuration'' button once again.
* In the ''Run/Debug Configurations'' dialog, click the {{Code|+}} button to create a new configuration based on a template.
* In the ''Run/Debug Configurations'' dialog, click the {{Code|+}} button to create a new configuration based on a template.
* Choose the "XQuery" template you configured earlier.
* Choose the "XQuery" template you configured earlier.
* Enter a name, e.g. "BaseX", into the ''Name'' field.
* Enter a name, e.g. "BaseX", into the ''Name'' field.
-
* The query processor should be preset to "BaseX 9.1.1 (BaseX)".
+
* The query processor should be preset to "BaseX [''Version''] (BaseX)".
-
* In the ''Script File'' field, enter the path to your query file.
+
* In the ''Run the query from'' area, either enter the path to your query file into the ''Local file'' field to limit the run configuration to that query or choose the ''Active editor file'' option to make the configuration run the script that is currently opened in the IntelliJ editor panel.
[[File:Intellij-xquery-configuration.png]]
[[File:Intellij-xquery-configuration.png]]
* Click ''Apply'' and then ''OK'' to close the ''Run/Debug Configurations'' dialog.
* Click ''Apply'' and then ''OK'' to close the ''Run/Debug Configurations'' dialog.
* Now, the configuration should be set and the green ''Run'' button should be available below the IntelliJ IDEA menu bar.
* Now, the configuration should be set and the green ''Run'' button should be available below the IntelliJ IDEA menu bar.
[[File:Intellij-run-button.png]]
[[File:Intellij-run-button.png]]
 +
 +
'''Execute Your Query'''
* If the configuration does not run as a standalone instance, make sure that BaseX is up and running.
* If the configuration does not run as a standalone instance, make sure that BaseX is up and running.
* Click the ''Run'' button to execute your query.
* Click the ''Run'' button to execute your query.
-
=XQuery Support + MarkLogic Debugger=
+
==Conclusion==
-
This section focuses on Grzegorz Ligas' [https://plugins.jetbrains.com/plugin/9757-xquery-support--marklogic-debugger XQuery Support plugin].  
+
The plugin is very well maintained! It adds support for various XQuery Implementations to the IntelliJ IDEA (among them BaseX). It provides syntax highlighting for XQuery and XML and detects syntactical errors while you type offering a description for each error. Queries are executed using Run Configurations for which you can configure various query processors, e.g. BaseX.
 +
 
 +
The plugin contains some minor flaws regarding the static binding of BaseX namespaces. A few namespaces are marked as unknown in the code, however, query execution in the BaseX backend works fine in spite of them. Also, the IntelliJ ''Find Usages'' and ''Go To'' options did not work as expected in some cases, especially with regard to functions and across modules. The plugin does not yet include a code completion feature.
 +
 
 +
Note that the usage of functions from imported or declared namespaces that do not exist in the namespace might not be marked as unknown. To highlight invalid functions, you may enable the ''XPath and XQuery > XPST: XPath static errors > XPST0017: Undefined function'' inspection in the ''Editor > Inspections'' section.
 +
 
 +
=XQuery Support Plugin=
 +
 
 +
This section focuses on Grzegorz Ligas' [https://plugins.jetbrains.com/plugin/7262-xquery-support XQuery Support plugin].  
==Installation==
==Installation==
After installing IntelliJ IDEA and BaseX, install the XQuery Support plugin by one of the following methods:
After installing IntelliJ IDEA and BaseX, install the XQuery Support plugin by one of the following methods:
-
===From the Start Screen===
 
-
[[File:intellij-startbildschirm.png]]
+
'''From the Start Screen'''
* Start IntelliJ IDEA and select ''Configure''→''Plugins''.
* Start IntelliJ IDEA and select ''Configure''→''Plugins''.
-
* In the Plugins window, select the tab ''Marketplace''.
+
* In the ''Plugins'' window, select the tab ''Marketplace''.
-
* Type "XQuery Support" into the ''Search plugins in marketplace'' field.
+
* Type "XQuery" into the ''Search plugins in marketplace'' field and press Enter.
-
* Click the ''Install'' button below the ''XQuery Support + MarkLogic Debugger'' plugin.
+
* Click the ''Install'' button below the ''XQuery Support'' plugin or click on the ''XQuery Support'' link to get more information on the plugin before installing it.
* You will be prompted to restart IDEA to load the new plugin.
* You will be prompted to restart IDEA to load the new plugin.
-
===From the IntelliJ IDEA Menu===
+
'''From the IntelliJ IDEA Menu'''
-
* Select ''Settings'' (Windows)/''Preferences'' (macOS) in the ''IntelliJ IDEA'' menu.
+
* Select ''Settings'' (Windows)/''Preferences'' (macOS) from the ''IntelliJ IDEA'' menu.
* In the Settings/Preferences window, select ''Plugins''.
* In the Settings/Preferences window, select ''Plugins''.
-
* In the Plugins window, select the tab ''Marketplace''.
+
* In the ''Plugins'' panel, select the tab ''Marketplace''.
-
* Type "XQuery Support" into the ''Search plugins in marketplace'' field.
+
* Type "XQuery" into the ''Search plugins in marketplace'' field and press Enter.
-
* Click the ''Install'' button below the ''XQuery Support + MarkLogic Debugger'' plugin.
+
* Click the ''Install'' button below the ''XQuery Support'' plugin or click on the ''XQuery Support'' link to get more information on the plugin before installing it.
* You will be prompted to restart IDEA to load the new plugin.
* You will be prompted to restart IDEA to load the new plugin.
==Setting Up==
==Setting Up==
-
===File Extensions and XQuery Flavor===
+
'''File Extensions and XQuery Flavor'''
* Start IntelliJ IDEA and navigate to ''Settings'' (Windows)/''Preferences'' (macOS) either using the ''Configure'' button on the start screen or the ''IntelliJ IDEA'' menu.
* Start IntelliJ IDEA and navigate to ''Settings'' (Windows)/''Preferences'' (macOS) either using the ''Configure'' button on the start screen or the ''IntelliJ IDEA'' menu.
* In the Settings/Preferences window, expand the ''Languages & Frameworks'' item, select ''XQuery'' and choose which default file extensions and which XQuery flavor you would like to use.
* In the Settings/Preferences window, expand the ''Languages & Frameworks'' item, select ''XQuery'' and choose which default file extensions and which XQuery flavor you would like to use.
Line 125: Line 147:
===Standalone===
===Standalone===
* In the ''Settings'' (Windows)/''Preferences'' (macOS) window, expand the ''Languages & Frameworks'' item and select ''XQuery Data Sources''.
* In the ''Settings'' (Windows)/''Preferences'' (macOS) window, expand the ''Languages & Frameworks'' item and select ''XQuery Data Sources''.
-
* Click on the {{Code|+}} button in the middle column, to add a new data source.
+
* Click on the {{Code|+}} button in the middle column to add a new data source.
* Select ''BaseX (native embedded)'' from the dropdown box.
* Select ''BaseX (native embedded)'' from the dropdown box.
* In the right-hand column, check the ''User defined XQJ Driver'' check box.
* In the right-hand column, check the ''User defined XQJ Driver'' check box.
* Use the  {{Code|+}} button below the check box to add the following {{code|jars}} from your BaseX distribution:
* Use the  {{Code|+}} button below the check box to add the following {{code|jars}} from your BaseX distribution:
** {{Code|basex/BaseX.jar}}
** {{Code|basex/BaseX.jar}}
-
** {{Code|basex/lib/basex-apj-9.1.1.jar}}
+
** {{Code|basex/lib/basex-apj-9.1.2.jar}}
** {{Code|basex/lib/basex-xqj-9.0.jar}}
** {{Code|basex/lib/basex-xqj-9.0.jar}}
** {{Code|basex/lib/xqj2-0.2.0.jar}}
** {{Code|basex/lib/xqj2-0.2.0.jar}}
Line 151: Line 173:
==Querying Your Data==
==Querying Your Data==
 +
 +
'''Create a New Project'''
* To create a new project choose the ''Create new project'' option from the start screen or select ''New''→''Project...'' from the ''File'' menu.
* To create a new project choose the ''Create new project'' option from the start screen or select ''New''→''Project...'' from the ''File'' menu.
* In the ''New Project'' dialog, choose ''Empty Project'' from the left-hand column and click the ''Next'' button.
* In the ''New Project'' dialog, choose ''Empty Project'' from the left-hand column and click the ''Next'' button.
-
* Enter a name and location for your project.
+
* Enter a name and location for your project and click on the ''Finish'' button.
-
* In the project view, create a new XQuery file, either by right-clicking on the project name and choosing ''New''''XQuery File'' or by selecting ''New''''XQuery File'' from the File menu. Enter a file name and click ''OK''.
+
 
-
* Type in your query.
+
'''Customize the XQuery Module'''
 +
* Click the ''Add Configuration'' button below the IntelliJ IDEA menu bar.
 +
[[File:Intellij-add-configuration.png]]
 +
* In the ''Run/Debug Configurations'' dialog, expand the Templates list and choose the ''XQuery Main Module'' entry.
 +
* Click on the ''Configure'' button next to the ''Data Source'' field and either choose the previously configured standalone version (''BaseX (native embedded)'' item) or the client version (''BaseX'' item) from the list.
 +
* Click ''Apply'' and then ''OK'' to close the ''Run/Debug Configurations'' dialog.
 +
 
 +
'''Create a Query File'''
 +
* In the project view, create a new XQuery file by right-clicking on the project name and choosing New→XQuery File. Enter a file name, select ''Main Module'' from the ''Kind'' dropdown and click OK.
 +
* Type in your query and save your file.
[[File:Intellij-query.png]]
[[File:Intellij-query.png]]
-
* Click the green ''Run'' button below the IntelliJ IDEA menu bar.
+
 
-
* In the ''Edit Configuration'' dialog, choose one of the two data sources from the dropdown box, either "BaseX" or "BaseX (native embedded)". If you select "BaseX", make sure that BaseX is up and running.
+
'''Create a New Configuration'''
-
* Click ''Run'' to execute your query.
+
* Click on the ''Add Configuration'' button once again.
 +
* In the ''Run/Debug Configurations'' dialog, click the {{Code|+}} button to create a new configuration based on a template.
 +
* Choose the "XQuery Main Module" template you configured earlier.
 +
* Enter a name, e.g. "BaseX", into the ''Name'' field.
 +
* The data source should be preset either to "BaseX (native embedded)" or ''BaseX'' depending on your processor configuration.
 +
* In the ''Main file'' field, enter the path to your query file.
 +
[[File:Intellij-xquery-configuration2.png]]
 +
* Click ''Apply'' and then ''OK'' to close the ''Run/Debug Configurations'' dialog.
 +
* Now, the configuration should be set and the green ''Run'' button should be available below the IntelliJ IDEA menu bar.
 +
[[File:Intellij-run-button.png]]
 +
 
 +
'''Execute Your Query'''
 +
* If the configuration does not run as a standalone instance, make sure that BaseX is up and running.
 +
* Click the ''Run'' button to execute your query.
 +
 
 +
==Conclusion==
 +
The plugin adds support for various XQuery Implementations to the IntelliJ IDEA (among them BaseX). It provides syntax highlighting for XQuery and XML and detects syntactical errors while you type offering a description for each error. Queries are executed using Run Configurations for which you can configure various query processors, e.g. BaseX. The plugin offers code completion for XQuery functions, integrated library modules, such as FunctX or the BaseX Module Library, and user-defined modules. IntelliJ’s Find Usages and Go To options seem to work fine for variables and functions, even across modules. Users can set XQuery-specific code style preferences.
 +
 
 +
This plugin also has a few minor drawbacks. If no path is specified, syntax highlighting marks user-defined modules as unknown, even if they reside in the designated BaseX module repository. However, the BaseX query processor, resolves them correctly during query execution. Error messages in the editor seem to be kept rather general and should me more specific.
 +
Parameter lists of code completion may be quite extensive and clog the screen.
 +
Leading tab space can be increased in user-defined steps, but neither decreased in single, nor user-defined steps.

Latest revision as of 10:15, 7 May 2019

This article is part of the Getting Started Section. It describes how to run XPath/XQuery code from within the IntelliJ IDEA IDE. There are currently two XQuery plugins for IntelliJ IDEA on the market:

Contents

[edit] Preparations

The following steps apply to all operating systems and both plugins:

[edit] xquery-intellij-plugin

This section focuses on Reece H. Dunn's xquery-intellij-plugin.

[edit] Installation

After installing IntelliJ IDEA and BaseX, install the xquery-intellij-plugin by one of the following methods:

From the Start Screen

Intellij-startbildschirm.png

From the IntelliJ IDEA Menu

[edit] Configuring The Processor

Intellij-xquery-settings-2.png

[edit] Querying Your Data

Create a New Project

Customize the XQuery Module

Intellij-add-configuration.png

Intellij-new-query-processor.png

Create a Query File

Create a New Configuration

Intellij-xquery-configuration.png

Intellij-run-button.png

Execute Your Query

[edit] Conclusion

The plugin is very well maintained! It adds support for various XQuery Implementations to the IntelliJ IDEA (among them BaseX). It provides syntax highlighting for XQuery and XML and detects syntactical errors while you type offering a description for each error. Queries are executed using Run Configurations for which you can configure various query processors, e.g. BaseX.

The plugin contains some minor flaws regarding the static binding of BaseX namespaces. A few namespaces are marked as unknown in the code, however, query execution in the BaseX backend works fine in spite of them. Also, the IntelliJ Find Usages and Go To options did not work as expected in some cases, especially with regard to functions and across modules. The plugin does not yet include a code completion feature.

Note that the usage of functions from imported or declared namespaces that do not exist in the namespace might not be marked as unknown. To highlight invalid functions, you may enable the XPath and XQuery > XPST: XPath static errors > XPST0017: Undefined function inspection in the Editor > Inspections section.

[edit] XQuery Support Plugin

This section focuses on Grzegorz Ligas' XQuery Support plugin.

[edit] Installation

After installing IntelliJ IDEA and BaseX, install the XQuery Support plugin by one of the following methods:

From the Start Screen

From the IntelliJ IDEA Menu

[edit] Setting Up

File Extensions and XQuery Flavor

Intellij-xquery-settings.png

[edit] Configuring The Processor

You can set up the plugin as a standalone processor or client.

[edit] Standalone

[edit] Client

This assumes that you already have a BaseX database named factbook.

Intellij-basex-data-source.png

[edit] Querying Your Data

Create a New Project

Customize the XQuery Module

Intellij-add-configuration.png

Create a Query File

Intellij-query.png

Create a New Configuration

Intellij-xquery-configuration2.png

Intellij-run-button.png

Execute Your Query

[edit] Conclusion

The plugin adds support for various XQuery Implementations to the IntelliJ IDEA (among them BaseX). It provides syntax highlighting for XQuery and XML and detects syntactical errors while you type offering a description for each error. Queries are executed using Run Configurations for which you can configure various query processors, e.g. BaseX. The plugin offers code completion for XQuery functions, integrated library modules, such as FunctX or the BaseX Module Library, and user-defined modules. IntelliJ’s Find Usages and Go To options seem to work fine for variables and functions, even across modules. Users can set XQuery-specific code style preferences.

This plugin also has a few minor drawbacks. If no path is specified, syntax highlighting marks user-defined modules as unknown, even if they reside in the designated BaseX module repository. However, the BaseX query processor, resolves them correctly during query execution. Error messages in the editor seem to be kept rather general and should me more specific. Parameter lists of code completion may be quite extensive and clog the screen. Leading tab space can be increased in user-defined steps, but neither decreased in single, nor user-defined steps.

Personal tools
Namespaces
Variants
Actions
Navigation
Print/export