Difference between revisions of "Integrating IntelliJ IDEA"

From BaseX Documentation
Jump to navigation Jump to search
 
(17 intermediate revisions by 2 users not shown)
Line 3: Line 3:
 
* 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/7262-xquery-support XQuery Support] 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 10: Line 11:
  
 
* Install either version of IntelliJ IDEA: [https://www.jetbrains.com/idea/#chooseYourEdition the Community or Ultimate edition].
 
* Install either version of IntelliJ IDEA: [https://www.jetbrains.com/idea/#chooseYourEdition the Community or Ultimate edition].
* Download your favorite [http://basex.org/download BaseX distribution] (JAR, ZIP, EXE).
+
* Download your favorite [https://basex.org/download BaseX distribution] (JAR, ZIP, EXE).
 
* Start BaseX (see [[Startup]]).
 
* Start BaseX (see [[Startup]]).
 
* Create a BaseX database (see [[Databases]]).
 
* Create a BaseX database (see [[Databases]]).
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==
Line 66: 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>Description = BaseX</code> (optional; if you leave this field blank, <code>[Implementation] [Version]</code> will be used as description)
 
** <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>
 
** <code>Username = admin</code>
 
** <code>Username = admin</code>
** <code>Password = admin</code>
+
** <code>Password = ...</code>
 
** If you tick the check box ''Create a standalone instance'', the fields ''Hostname'', ''Database port'', ''Username'', and ''Password'' remain empty.
 
** If you tick the check box ''Create a standalone instance'', the fields ''Hostname'', ''Database port'', ''Username'', and ''Password'' remain empty.
 
[[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'''
 
'''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, e.g. <code>db:open("factbook")</code>, and save your file.
+
* Type in your query, e.g. <code>db:get("factbook")</code>, and save your file.
  
 
'''Create a New Configuration'''
 
'''Create a New Configuration'''
Line 89: Line 90:
 
* 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.
Line 99: Line 100:
 
* 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.
 +
 +
==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, code completion 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.
 +
 +
BaseX's admin log can be accessed and displayed using the '''Query Log''' button on the bottom left corner of the IntelliJ IDEA project window.
 +
 +
The plugin contains some minor flaws regarding the use of functions declared in user-defined modules. Such functions are not included in the code completion list and marked as unknown in the code. However, query execution in the BaseX backend works fine nonetheless.
  
 
=XQuery Support Plugin=
 
=XQuery Support Plugin=
Line 158: Line 167:
 
** <code>Database name = factbook</code>
 
** <code>Database name = factbook</code>
 
** <code>Username = admin</code>
 
** <code>Username = admin</code>
** <code>Password = admin</code>
+
** <code>Password = ...</code>
 
* Select ''Apply'', then ''OK'' and your BaseX {{code|factbook}} database is ready to query.
 
* Select ''Apply'', then ''OK'' and your BaseX {{code|factbook}} database is ready to query.
  
Line 193: Line 202:
 
* 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'''
 
'''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.
 +
 +
==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, 25 July 2022

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:

  • The xquery-intellij-plugin by Reece H. Dunn.
  • The 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 XML editor integrated into the BaseX GUI to edit and query your XML data!

Preparations[edit]

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

xquery-intellij-plugin[edit]

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

Installation[edit]

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

From the Start Screen

 

  • Start IntelliJ IDEA and select ConfigurePlugins.
  • In the Plugins window, select the tab Marketplace.
  • Type "XQuery" into the Search plugins in marketplace field.
  • Click the Install button below xquery-intellij-plugin.
  • You will be prompted to restart IDEA to load the new plugin.

From the IntelliJ IDEA Menu

  • Select Settings (Windows)/Preferences (macOS) in the IntelliJ IDEA menu.
  • In the Settings/Preferences window, select Plugins.
  • In the Plugins window, select the tab Marketplace.
  • Type "XQuery" into the Search plugins in marketplace field.
  • Click the Install button below xquery-intellij-plugin plugin.
  • You will be prompted to restart IDEA to load the new plugin.

Configuring The Processor[edit]

  • Start IntelliJ IDEA and navigate to Settings (Windows)/Preferences (macOS) either using the Configure button from the start screen or the IntelliJ IDEA menu.
  • In the Settings/Preferences window, expand the Languages & Frameworks item and select XQuery.
  • Make the choices for your system from the dropdown boxes, e.g.:
    • Implementation = BaseX
    • Implementation version = BaseX 9.1
    • Default XQuery version = XQuery 3.1
    • Dialect for XQuery 3.0 = BaseX
    • Dialect for XQuery 3.1 = BaseX

 

  • Click Apply to store your XQuery settings and then OK to exit the dialog.

Querying Your Data[edit]

Create a New Project

  • To create a new project choose the Create new project option from the start screen or select NewProject... from the File menu.
  • 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 and click on the Finish button.

Customize the XQuery Module

  • Click the Add Configuration button below the IntelliJ IDEA menu bar.

 

  • In the Run/Debug Configurations dialog, expand the Templates list and choose the XQuery entry.
  • Click on the three dots ... next to the Query Processor dropdown box.
  • In the Manage Query Processors dialog, click on the + button.
  • In the New Query Processor Instance dialog, set the following preferences:
    • Description = BaseX (optional; if you leave this field blank, [Implementation] [Version] will be used as description)
    • Implementation = BaseX (should be preset!)
    • JAR File = BaseX.jar (name and location of the JAR file may differ depending on your BaseX distribution and version)
    • Hostname = localhost
    • Database port = 1984
    • Username = admin
    • Password = ...
    • If you tick the check box Create a standalone instance, the fields Hostname, Database port, Username, and Password remain empty.

 

  • Click OK to exit the New Query Processor Instance dialog.
  • 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 [Version] (BaseX)". If not, select it from the dropdown box.
  • 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 NewFile or by selecting NewFile from the File menu. Enter a file name and click OK.
  • Type in your query, e.g. db:get("factbook"), and save your file.

Create a New Configuration

  • Click on the Add Configuration button once again.
  • In the Run/Debug Configurations dialog, click the + button to create a new configuration based on a template.
  • Choose the "XQuery" template you configured earlier.
  • Enter a name, e.g. "BaseX", into the Name field.
  • The query processor should be preset to "BaseX [Version] (BaseX)".
  • 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.

 

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

 

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[edit]

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, code completion 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.

BaseX's admin log can be accessed and displayed using the Query Log button on the bottom left corner of the IntelliJ IDEA project window.

The plugin contains some minor flaws regarding the use of functions declared in user-defined modules. Such functions are not included in the code completion list and marked as unknown in the code. However, query execution in the BaseX backend works fine nonetheless.

XQuery Support Plugin[edit]

This section focuses on Grzegorz Ligas' XQuery Support plugin.

Installation[edit]

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

From the Start Screen

  • Start IntelliJ IDEA and select ConfigurePlugins.
  • In the Plugins window, select the tab Marketplace.
  • Type "XQuery" into the Search plugins in marketplace field and press Enter.
  • 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.

From the IntelliJ IDEA Menu

  • Select Settings (Windows)/Preferences (macOS) from the IntelliJ IDEA menu.
  • In the Settings/Preferences window, select Plugins.
  • In the Plugins panel, select the tab Marketplace.
  • Type "XQuery" into the Search plugins in marketplace field and press Enter.
  • 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.

Setting Up[edit]

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.
  • 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.
  • Click Apply to store your XQuery settings.

 

Configuring The Processor[edit]

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

Standalone[edit]

  • In the Settings (Windows)/Preferences (macOS) window, expand the Languages & Frameworks item and select XQuery Data Sources.
  • Click on the + button in the middle column to add a new data source.
  • Select BaseX (native embedded) from the dropdown box.
  • In the right-hand column, check the User defined XQJ Driver check box.
  • Use the + button below the check box to add the following jars from your BaseX distribution:
    • basex/BaseX.jar
    • basex/lib/basex-apj-9.1.2.jar
    • basex/lib/basex-xqj-9.0.jar
    • basex/lib/xqj2-0.2.0.jar
  • Click Apply to store your settings.

Client[edit]

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

  • In the Settings (Windows)/Preferences (macOS) window, expand the Languages & Frameworks item and select XQuery Data Sources.
  • Click on the + button in the middle column to add a new data source.
  • Select BaseX from the dropdown box.
  • In the right-hand column, fill in the appropriate connection details, e.g. default values:
    • Host = localhost
    • Port = 1984
    • Database name = factbook
    • Username = admin
    • Password = ...
  • Select Apply, then OK and your BaseX factbook database is ready to query.

 

Querying Your Data[edit]

Create a New Project

  • To create a new project choose the Create new project option from the start screen or select NewProject... from the File menu.
  • 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 and click on the Finish button.

Customize the XQuery Module

  • Click the Add Configuration button below the IntelliJ IDEA menu bar.

 

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

 

Create a New Configuration

  • Click on the Add Configuration button once again.
  • In the Run/Debug Configurations dialog, click the + 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.

 

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

 

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[edit]

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.