Eclipse Plugin Setup Instructions

Sam Neth and Eric Bloch
Last updated 2011-09-14

As of MarkLogic 6, Java developers now have the additional option of using the MarkLogic Java API

XQDT is a set of open source plugins for the Eclipse IDE, providing support for syntax highlighting and content-assisted editing of XQuery modules, and a framework for executing and debugging modules in a supported XQuery interpreter.  The MarkLogic-specific extensions currently available add support for MarkLogic's syntax extensions, and auto-completion and integrated reference material for the entire MarkLogic API.  Modules can be executed on the server, with results displayed in the IDE.  Debugging is not yet supported.

System Requirements

Java

Eclipse requires but does not include a Java Virtual Machine.  Most developers will already have Java installed, though non-Java developers on Windows machines may need to install Java before installing Eclipse.  Java can generally be obtained here:

http://www.oracle.com/technetwork/java/javase/downloads/index.html

While many versions of Java are capable of running Eclipse without any problems, if you have difficulty with these instructions, the version of Java installed on your machine may be the source of the problem.  Check eclipse.org for information about versions of Java used in formal testing of Eclipse:

http://www.eclipse.org/downloads/moreinfo/jre.php

Eclipse IDE

The screenshots herein are from Mac OS X, but binaries for the Eclipse IDE are available for virtually any desktop environment, and XQDT should work on any of them.  The version of XQDT we provide can be used with Eclipse 3.6 (Helios) or Eclipse 3.7 (Indigo).  Unless you need to run a different version, 3.6 (Helios) is recommended.

MarkLogic Server

The MarkLogic capabilities of XQDT can interoperate with any version of MarkLogic Server.  The server need not be running on the workstation where the IDE is installed.  An XDBC server must be configured through which XQDT can send semantic validation and module execution requests.

Set Up MarkLogic Server

It is beyond the scope of this document to describe the procedure for downloading and installing MarkLogic Server, or to detail the configuration of the server.  Assuming you have the server installed and running, enabling XQDT simply requires creating an XDBC server.  

In the Admin Interface, navigate to Groups > Default > App Servers.  

Select the Create XDBC tab, fill in the required fields, and click Ok

Remember the port number for the new server for use in setting up XQDT.

Install Eclipse IDE

Before installing XQDT, you need a copy of Eclipse IDE.  You will generally be able to install XQDT in an existing copy, but if you prefer to keep your XQDT environment separate, or run into trouble getting XQDT to work properly, you may wish to install a fresh copy.  You can download an installer from one of the following links:

Eclipse 3.6.2 (Helios) [ Recommended ]

http://www.eclipse.org/downloads/packages/release/helios/sr2

Eclipse 3.7 (Indigo)

http://www.eclipse.org/downloads

Launch Eclipse IDE

When you launch Eclipse you will be prompted for a workspace location.  The workspace will be the parent directory of your eclipse projects.  You may wish to check the box indicating that Eclipse should use your workspace at startup automatically.  The workspace can always be changed from within Eclipse by selecting File > Switch Workspace from the menu.

Workspace Launcher

Install XQDT as a dropin

The current version of XQDT from the Eclipse update site will not work with MarkLogic.  While this issue remains, kindly download a copy of XQDT from http://developer.marklogic.com/download/code/eclipse/xqdt-dropin.zip and unpack it into the dropins folder underneath Eclipse.  You should see the following hierarchy underneath the main Eclipse folder with the zip unpacked into the dropins folder.
 
Eclipse Folder
 
Restart Eclipse when you are done.
 
Note:  MarkLogic has verified this method of installing XQDT works in a virgin install of Eclipse 3.6.2 (Helios) as well as Eclipse 3.7 (Indigo), but recommends you use Eclipse 3.6.2.  It is possible that these jars, when installed in 3.7, may cause conflicts in the future.  If you have issues installing XQDT this way in non-virgin Eclipse installations, we're happy to help.  So, let us know.

Pre-configured Eclipse IDE + XQDT for Windows

If you are using a Windows environment, you may find it easier to install a pre-configured version of Eclipse.  This is a 32-bit version of eclipse, which requires a 32-bit version of Java.  You can also find a copy of Windows 32-bit Java at java32_usefor64too.zip. This version of Java will run on 32-bit or 64-bit Windows machines.

[ This package contains an older version of the software, so self-installation is recommended. ]

Create your first XQuery Project

From the menu bar, select File > New > Project...

File > New > Project

Choose XQuery / XQuery Project and click [Next...]

New Project

Enter a name for your project, and click [Configure interpreters...] to configure XQDT to communicate with MarkLogic Server.

New XQuery ProjectIn the interpreters dialog, click [Add...]

Configure Interpreters

Change Interpreter type to "MarkLogic Server" and configure the connection with the URL for accessing your XDBC server, (Example: xcc://localhost:8888), and the username and password for authentication of requests to the server.

Add Interpreter

Click [Ok] to save the new interpreter, and again to exit the interpreters dialog.

Click [Finish]

When Eclipse asks if you would like to switch to the XQuery perspective, click [Yes]

XQuery Perspective

Create an XQuery Module

From the menu bar, select File > New > XQuery Module

File > New > XQuery Module

(This option appears if you're in the XQuery perspective.  You can also select it from the New > Other... dialog)

Choose a module type and give it a name, click [Finish].

New XQuery Module

Test an XQuery Module

From a module editor window, ensure the module is saved, and run it by selecting Run > Run from the menu bar.  There are a number of other ways to run a module, using context menus or toolbar buttons.  Your results will be displayed in the Eclipse Console panel.  Note that only main modules can be executed.  

Test XQuery

Helpful Hints

XQuery Version Prolog

XQDT uses the version prolog to enable MarkLogic-specific features.  It is always good practice to begin your modules with a version prolog, in order to guarantee correct behavior independent of the default settings of a particular MarkLogic Server instance.  In general, your modules should start with the following:

xquery version "1.0-ml";

XQuery Module Directory

XQDT requires that XQuery modules be stored inside your project directory; XQuery modules outside the project directory can be opened and the XQuery editor will be mostly functional, but some features will not work in this scenario.

Resources

XQDT project page at eclipse.org:

http://wiki.eclipse.org/XQDT

Please file bug or enhancement requests in eclipse bugzilla; free account setup is quick and painless.

XQDT commercial adopters website / blog:

http://www.xqdt.org/

Comments

  • Error: Could not find or load main class admin :--error is coming
    • You'll be better served reporting problems on our mailing list or SO http://developer.marklogic.com/qa
  • Hi, Excellent tutorial, thx. I am new to ML now I have installed ML6 on my laptop. The default XDBC server, (Example: xcc://localhost:8888) seems not to be there? How can I find if and where the XDBC server is running? (edit: see http://docs.marklogic.com/guide/admin/xdbc#id_21458) thx hugo
    • see here how to setup an XDBC server in ML http://docs.marklogic.com/guide/admin/xdbc#id_21458
  • From Install Eclipse IDE: This is super confusing... From the documentation above: <pre> <p>Eclipse 3.6.2 (Helios)[<span style="color: #339966;">Recommended</span>]</p><p style="padding-left: 30px;"><a href="http://www.eclipse.org/downloads/">http://www.eclipse.org/downloads/packages/release/helios/sr2</a></p> </pre> The link goes to http://www.eclipse.org/downloads/, which is the most recent eclipse download page, and when I search for eclipse 3.6.2 in a search engine, I see there are no packages to download (http://www.eclipse.org/downloads/packages/eclipse-classic-362/heliossr2/) Can you please either fix the link, or advise on another version of eclipse? Thanks!
  •  looks like this basicly works with Juno
  • The XQDT version on the Eclipse update site doesn't currently have MarkLogic support.  For now, we've updated this page to include instructions on how to install XQDT as an Eclipse DropIn.   See http://developer.marklogic.com/learn/xqdt-setup#n6b25bad7a26eb99d
  • For Eclipse 3.7 Indigo org.eclipse.wst.xquery.marklogic.feature is disabled.
    • The XQDT version on the Eclipse update site doesn't currently have MarkLogic support.  For now, we've updated this page to include instructions on how to install XQDT as an Eclipse DropIn.   See http://developer.marklogic.com/learn/xqdt-setup#n6b25bad7a26eb99d
    • Thanks, we're looking into this.
  • Hi, folks! Since a few days Incubator has commented out MarkLogic from the installation XML file located on http://download.eclipse.org/webtools/incubator/repository/xquery/milestones/ Is there any workaround (e.g. manual installation) getting XQTD with MarkLogic to work?
    • Thanks, we're looking into this.
  • My applications were running in RAD 7.0 built on eclipse 3.2.2. It would be great if we have any patches to support xqdt in this version.
  • Peter, during installation, it failed to find the Eclipse DLTK plugin (org.eclipse.dltk...). Possibly you need to add the Eclipse update site to your Eclipse setup. In Eclipse, go to Help > Install New Software and add the Galileo update (I think that's correct for Eclipse 3.5): http://download.eclipse.org/releases/galileo. 
  • I'm running Ubuntu 10.10 with MarkLogic Server 4.2 Standard Edition.  I just did a fresh install of Eclipse.  Here's what's in my About... window: Version: 3.5.2Build id: M20100211-1343I then followed the instructions on this page, which are very similar to those found on the following page: http://wiki.eclipse.org/XQDT/InstallationOn the "Install Details" page, it says that "The operation cannot be completed." Here are the details:Cannot complete the install because one or more required items could not be found.   Software being installed: MarkLogic XQDT Adapter 0.8.0.201102021210 (org.eclipse.wst.xquery.marklogic.feature.feature.group 0.8.0.201102021210)   Missing requirement: XQDT MarkLogic Debugger Plug-in 0.8.0.201102021210 (org.eclipse.wst.xquery.debug.debugger.marklogic 0.8.0.201102021210) requires 'bundle org.eclipse.dltk.core [2.0.0,3.0.0)' but it could not be found   Cannot satisfy dependency:     From: MarkLogic XQDT Adapter 0.8.0.201102021210 (org.eclipse.wst.xquery.marklogic.feature.feature.group 0.8.0.201102021210)     To: org.eclipse.wst.xquery.debug.debugger.marklogic [0.8.0.201102021210]I've tried looking for the required dependency.  I think I found something here:http://git.eclipse.org/c/webtools/org.eclipse.webtools.incubator.git/plain/sourceediting/plugins/org.eclipse.wst.xquery.debug.debugger.marklogic/src/org/eclipse/wst/xquery/debug/engines/marklogic/However, I don't have the slightest clue what to do with it at this point. I am new to Eclipse/Java/xQuery/MarkLogic so I'm at a loss.  (11 years of .NET experience isn't helping so far.)
    • Hi Peter, I had the same problem when I tried installing XQDT on Eclipse 3.7 (Indigo).   I found that installing the DLTK 2.0 Core Framework from http://download.eclipse.org/technology/dltk/updates/ got around that dependency.  I outlined the steps I took for all the dependencies (plus a couple of screengrabs) here: http://tinyurl.com/3uo7xpl Hope that helps! Alex.
      • That seemed to do the trick.  I got past the dependency issues.  Now on to loading up our ML application project files.  Thanks!