You are viewing an old version of this page. View the current version.

Compare with Current View Page History

« Previous Version 28 Next »

Table of contents

Sling IDE Tooling User Guide

Prerequisites

The Sling IDE tooling is known to work on Eclipse versions starting with Kepler. There is a hard dependency on the faceted project framework, which is included in the 'Eclipse IDE for Java EE Developers' package. If you're running a different package, you can always install it from the main Eclipse update site.

There is an optional feature which relies on m2eclipse. For now it only provides project creation wizards, so if you don't use Maven you don't have to install it.

Installation

There is no official release yet, but I ( Robert Munteanu ) am maintaining unnoficial preview builds at http://people.apache.org/~rombert/sling/ide/preview/ . Feel tree to give them a try.

Overall concepts

The Sling IDE tooling is centered around the Server and Module concepts. A Server is an instance of a Sling launchpad - or derivatives such as Adobe CQ - on which you deploy your content. A Module is a collection of resources grouped into a single Eclipse project which can be deployed onto one or multiple Servers.

The tooling supports content and bundle modules. Content modules typically hold Sling scripts - like JSP and ESP files, client-side resources like CSS and JSS file, but also arbitrary repository content. Content modules support support setting JCR properties for nodes other than nodes and files, based on the FileVault serialization format. You can read mode about FileVault at the Apache Jackkrabit FileVault docs Bundle modules represent a single OSGi bundle.

Server definition

To create a new Sling launchpad server you will need to start a Sling launchpad outside of Eclipse. We do not yet support starting Sling Launchpad instances from Eclipse.

To kick off, create a new Sling Launchpad Server using the File -> New -> Other... menu entry.

In the resulting wizard, select the External Sling Launchpad category and enter the host name.

Once that is done, press finish.

Server configuration

The server will appear in the servers view. You can double-click on it to review the settings which were automatically provided.

There are a couple of important settings in the server definition page:

  • port: used for connecting to the server
  • publishing interval: controls how fast the resources will be published after a change. We recommend setting the interval to 0, for fast deploy times
  • username, password, context path: controls the connection details to the Sling instance.
  • debug port: used for connecting in debug mode

For working with OSGi bundles, a special support bundle must be installed to support fast bundle redeployment. If it is not present, you can install it using the hyperlink from the Install section.

You can now connect to the server

Content sync

Content projects are required to have at least

  1. a jcr_root directory, which contains the serialized content of the repository
  2. a META-INF/vault/filter.xml file, which contains the workspace filter definition

All changes performed in the local workspace are synchronized to the repository, given that they are included in the workspace filter definition.

Creating a new content project

Creating a new Sling content project is easily done by using the new Sling Content Project Wizard. To kick off, start by selected File -> New -> Project and select Sling Content Project under the Sling category.

You will then be asked to name the project and select its location.

Finally, you can select whether to add the project to an existing server or create a new one.

Once you press finish, the project will be created and deployed to the server.

Converting existing projects

To mark a project as being a Sling content module, click it in the Project Explorer and Select Configure -> Convert to Sling Content Project... . A dialog will pop up and will ask you to confirm the inferred location of the jcr_root directory. You can also change this from the project properties, the Sling page.

Content navigator

In the Project Explorer view there is an additional 'jcr_root' contribution to the project. It is denoted by a folder icon with a small web overlay. This contribution provides a logical view over the repository content, taking into account JCR metadata. As such, .content.xml files will be folded into the corresponding node.

Node properties can be edited in a distinct JCR properties view.

filter.xml - workspace filter definition

A content project does not synchronize all its contents to the workspace. Instead, it looks for a filter.xml file which defines which content is included in synchronization operations. More information about the filter.xml file format and semantics can be found at FileVault docs - Workspace Filter

Deploying projects on the server

To deploy a project on the server, open the Servers view and use the Add and Remove... dialog to add one or more modules.

After content projects are deployed, each change will cause the changed resources to be updated in the repository.

Bundle sync

The only requirement for bundle projects is that they are Java projects which generate an exploded OSGi bundle in their output directory. That requires at least a valid OSGi Manifest located in META-INF/MANIFEST.MF, but typically one of more Java classes. Other auxiliary files, such as Declarative Service descriptors, must also be placed under the project's output directory.

Creating a new bundle project

Creating a new Sling bundle project is easily done by using the new Sling Bundle Project Wizard. This wizard is only available when the Maven-based integration is installed. To kick off, start by selected File -> New -> Project and select Sling Bundle Project under the Sling category.

The next page allows you to select the archetype to use. It's recommended to select the latest version of the archetype.

You will be asked to configure the archetype's properties.

Finally, you can select whether to add the project to an existing server or create a new one.

Once you press finish, the project will be created and deployed to the server.

Converting existing projects

To mark a project as being a Sling bundle module, right click it in the Project Explorer and Select Configure -> Convert to Sling Bundle Project... . A dialog will appear with all the candidate Sling bundle project from the workspace so that you can quickly select multiple projects.

Deploying projects on the server

To deploy a project on the server, open the Servers view and use the Add and Remove... dialog to add one or more modules.

After OSGi bundle projects are deployed, each change will cause the bundle to be redeployed on the server.

Troubleshooting

Gathering debug information

All operations that are performed on the Sling launchpad are logged in the Sling console. To view these operations, open the Eclipse console view and select Open Console -> Sling Console.

Additional information can be obtained by enabling the Eclipse platform tracing facility. To do so, open the Eclipse preferences and navigate to General -> Tracing. Make sure that 'Enable tracing' is checked and all options under 'Sling IDE Tooling' are enabled.

Why do I get an errror about "No DS descriptor found at..."?

Bundle deployment assumes that the OSGi bundle is packaged into the project's output directory. This includes:

  • the manifest
  • compiled class files
  • resources
  • Declarative Services descriptors

One often-occuring situation is that a Maven project using the maven-scr-plugin generates the descriptors outside of target/classes, typically in target/scr-plugin-generated. To fix this, make sure that you're using the maven-scr-plugin 1.15.0 or newer and that you have not set a custom outputDirectory.

Known issues

The content sync implementation tries to mimic the FileVault semantics as closely as possible. However, it is possible that some more exotic content structures will not be handled properly. Some of the problems we're are of are:

 

  • No labels