Documentation for Toromiro JCR Browser and Editor

Technical Documentation for subshell's Toromiro JCR Browser and Editor including adapters for Sophora CMS, Magnolia CMS, Adobe CRX, and Hippo CMS.

First Steps

Download

Download Toromiro from this page: Toromiro Download

Run It

Unzip the downloaded package, and run the Toromiro executable:

  • On Windows, run toromiro.exe.
  • On Mac, run toromiro.app.
  • On Linux, run toromiro.

When you run Toromiro for the first time, it will ask for a license key. Enter the 30-day evaluation license key from the download page.

Connect To The Demo Repository

We have a public demo repository running on our servers. Connect to it using the following steps:

  • Select File >> New >> Repository from the main menu.
  • A dialog will pop up where you'll have to enter the following connection details:
  • Name: Toromiro Demo Repository
  • Group: <leave empty>
  • JCR adapter: Apache Jackrabbit 2.4 (RMI)
  • Repository URL: rmi://cmsdemo.sophoracms.com:1999/repository
  • Username: admin
  • Password: admin
  • Workspace: <leave empty>
  • Observation: Checked
  • To connect to the Toromiro demo repository, double-click the new entry "Toromiro Demo Repository" in the Repository Browser view.

The following screenshot shows the repository settings:

subshell's Toromiro Repository Settings

Once connected to the demo repository, try the following:

You can browse its contents in the Repository Browser.

You can search for documents in the Repository Search using an XPath query. E.g. enter the following query:

//element(*, sophora-content-nt:story)

You can search for documents by UUID by clicking on the UUID button in the Repository Search view. E.g. search for the UUID 43c945f0-97d3-42fe-9c9e-e2c92f70d9d7.

View node type definitions as diagrams or CND in the Repository Node Types view.

Download the User Guide (PDF) for more information about using Toromiro.

Connect To A Jackrabbit Repository

Toromiro can be used to connect to Apache Jackrabbit repositories in different ways.

Connect To Jackrabbit Server by RMI

1. Download the jackrabbit-standalone jar from the Apache Software Foundation. This example uses the version 2.1.3.

2. Run it using: java -jar jackrabbit-standalone-2.1.3.jar

3. In Toromiro, create a repository connection with the following details:

  • Name: Jackrabbit Standalone
  • JCR adapter: Apache Jackrabbit 2.1 (RMI)
  • Repository URL: http://localhost:8080/rmi
  • Username: anything
  • Password: anything
  • Workspace: <leave empty>
  • Observation: Checked

Connect To Jackrabbit Server by WebDAV

This example shows how to connect to a remote Jackrabbit repository using WebDAV. In this example, we'll connect to the Jackrabbit Webapp, which can be installed as follows:

  • Download a Tomcat server from the Apache software foundation and extract the zip file to your file system. This example uses the version 7.0.40.
  • Download the Jackrabbit Webapp war file from the Apache software foundation and copy it into the webapps folder of the Tomcat. This example uses the version 2.6.2.
  • Copy the jcr-2.0.jar file into the lib folder of the Tomcat. You can get the file from the final release of the JSR 283 specification or any Maven repository.
  • Start the Tomcat server using the startup file in the bin folder of the Tomcat.
  • Open http://localhost:8080/jackrabbit-webapp-2.6.2/ in your favorite browser and create a new content repository

In Toromiro, create a repository connection with the following details:

  • Name: Jackrabbit WebDAV
  • JCR adapter: Apache Jackrabbit 2.6 (WebDAV)
  • Repository URL: http://localhost:8080/jackrabbit-webapp-2.6.2/server
  • Username: admin
  • Password: admin
  • Workspace: <leave empty>
  • Observation: Checked

Note that you can connect to that repository by RMI as well:

  • Name: Jackrabbit RMI
  • JCR adapter: Apache Jackrabbit 2.6 (RMI)
  • Repository URL: http://localhost:8080/jackrabbit-webapp-2.6.2/rmi or //localhost/jackrabbit.repository
  • Username: admin
  • Password: admin
  • Workspace: <leave empty>
  • Observation: Checked

Create And Edit A Local Jackrabbit Repository Directly

Toromiro can also be used to create and edit a local Jackrabbit repository directly. Instead of configuring an url to connect to, the directory where the repository is located / will be created has to be given, as well as the path to a repository.xml configuration file.

Create A Repository

Create a directory for the repository in your file system, e.g. c:/temp/repo. Copy the attached repository.xml into this directory. In Toromiro, create a repository connection with the following details:

  • Name: Jackrabbit Local
  • JCR adapter: Apache Jackrabbit 2.1 (Local, Derby 10.3.1.4)
  • Home directory: c:/temp/repo
  • Configuration file: c:/temp/repo/repository.xml
  • Username: anything
  • Password: anything
  • Workspace: <leave empty>
  • Observation: Checked

When you connect to the repository for the first time, it will be created with the default Jackrabbit content in the given directory.

Database

The example above uses a Derby persistence manager which is supported by Toromiro out of the box. If your repository uses another persistence manager, e.g. a h2 database, you have to configure the JDBC driver in the toromiro.ini file (only since Toromiro 1.13.0). To do so set the property JDBC_DRIVER to the path of your driver jar file. Afterwards the "Apache Jackrabbit <version> (Local, Derby <version>)" JCR adapters will work with the configured JDBC driver, too.

Here is an example of the toromiro.ini file (Windows 64 bit, h2 database). Note that JDBC_DRIVER is a system property and must be set after -vmargs. Moreover the toromiro.ini file must end with an empty line.

-startup
plugins/org.eclipse.equinox.launcher_1.0.201.R35x_v20090715.jar
--launcher.library
plugins/org.eclipse.equinox.launcher.win32.win32.x86_64_1.0.200.v20090519
-vmargs
-Xmx1024m
-XX:MaxPermSize=128m
-DJDBC_DRIVER=C:/path/to/h2driver/h2-1.4.180.jar

Connect To An Existing Jackrabbit Repository

Instead of creating the repository with Toromiro, you can also open an existing Jackrabbit repository directly. For example, you can open a repository from a Sophora CMS installation without needing to start the Sophora server.

There are, however, limitations: Be sure to use an adapter with the exact same version of Jackrabbit and Derby as the CMS that created the repository. If non-matching versions are used, Jackrabbit might upgrade the database schema to a new version.

Connect To Your CMS

This section shows how to access different content management systems with Toromiro using a remote connection. Toromiro has adapters for accessing several JCR implementations, most notably Apache Jackrabbit.

When using a Jackrabbit RMI adapter, the version number of the adapter has to be roughly the same as the version of the Jackrabbit server used in the CMS. E.g. if the CMS uses Jackrabbit 2.1.1, use the "Apache Jackrabbit 2.1 (RMI)" adapter in Toromiro. Using an adapter with a non-matching version might work, but could lead to exceptions.

Sophora CMS

Sophora is accessible using Jackrabbit RMI. The user that is used for the connection must have the admin role. In Toromiro, create a repository connection with the following details:

  • Name: Sophora
  • JCR adapter: For Sophora version <= 1.35. select 'Apache Jackrabbit 1.6.4 (RMI)', since Sophora 1.36. 'Apache Jackrabbit 2.4 (RMI)' is required
  • Repository URL: rmi://<sophora server address>:1199/repository
  • The port here is the port set in the sophora.properties of your Sophora installation using the property sophora.rmi.registryPort.
  • Username: admin
  • Password: admin
  • Workspace: <leave empty>
  • Observation: Checked

Magnolia CMS

The following introductions describe how to connect to the repository of a Magnolia Community Edition.

Magnolia 4.5.7

The following introduction describes how to connect to the author repository of Magnolia Community Edition 4.5.7. Since a connection to a running Magnolia instance over RMI is not possible, a direct connection to the repository has to be used. To do so, stop the Magnolia server and create a repository connection with the following details in Toromiro:

  • Name: Magnolia 4.5.7
  • JCR adapter: Apache Jackrabbit 1.6.4 (Local, Derby 10.5.3.0_1)
  • Home directory: <magnolia installation folder>\magnolia-4.5.7\apache-tomcat-6.0.32\webapps\magnoliaAuthor\repositories\magnolia
  • Configuration file: <magnolia installation folder>\magnolia-4.5.7\apache-tomcat-6.0.32\webapps\magnoliaAuthor\WEB-INF\config\repo-conf\jackrabbit-bundle-derby-search.xml
  • Username: superuser
  • Password: superuser
  • Workspace: One of the following: "website", "config", "users", "userroles", "usergroups", "mgnlSystem" or "mgnlVersion"
  • Observation: Checked

In the specified configuration file (jackrabbit-bundle-derby-search.xml) change the security entry from ...

<Security appName="magnolia"> 
 	 <SecurityManager class="org.apache.jackrabbit.core.DefaultSecurityManager"/> 
 	 <AccessManager class="org.apache.jackrabbit.core.security.DefaultAccessManager"></AccessManager> 
  	<!-- login module defined here is used by the repo to authenticate every request. 
  	not by the webapp to authenticate user against the webapp context
  	 (this one has to be passed before thing here gets invoked -->
 	  <LoginModule class="info.magnolia.jaas.sp.jcr.JackrabbitAuthenticationModule"> </LoginModule>
</Security>

... to ...

<Security appName="Jackrabbit"> 
  	<AccessManager class="org.apache.jackrabbit.core.security.SimpleAccessManager"></AccessManager> 
  	<LoginModule class="org.apache.jackrabbit.core.security.SimpleLoginModule"> 
  		<param name="anonymousId" value="anonymous" /> 
  	</LoginModule> 
</Security>

To connect to the public repository just replace the folder magnoliaAuthor in home directory and configuration file path to magnoliaPublic. Of course, the configuration file (jackrabbit-bundle-derby-search.xml) of magnoliaPublic has to be modified like above, too.

Magnolia 4.4.2

The following introduction describes how to connect to the author repository of Magnolia Community Edition 4.4.2. Since a connection to a running Magnolia instance over RMI is not possible, a direct connection to the repository has to be used. To do so, stop the Magnolia server and create a repository connection with the following details in Toromiro:

  • Name: Magnolia 4.4.2
  • JCR adapter: Apache Jackrabbit 1.6.2 (Local, Derby 10.3.1.4)
  • Home directory: <magnolia installation folder>\magnolia-4.4.2\apache-tomcat-6.0.29\webapps\magnoliaAuthor\repositories\magnolia
  • Configuration file: <magnolia installation folder>\magnolia-4.4.2\apache-tomcat-6.0.29\webapps\magnoliaAuthor\WEB-INF\config\repo-conf\jackrabbit-bundle-derby-search.xml
  • Username: superuser
  • Password: superuser
  • Workspace: One of the following: "website", "config", "users", "userroles", "usergroups", "mgnlSystem" or "mgnlVersion"
  • Observation: Checked

To connect to the public repository just replace the folder magnoliaAuthor in home directory and configuration file path to magnoliaPublic.

Adobe CRX

Adobe CRX uses Apache Jackrabbit internally, but is not accessible using plain Jackrabbit RMI. Instead, a CRX RMI library has to be used for the connection. Toromiro can use third-party JCR libraries using a custom JCR adapter.

The following example shows how to connect to Adobe CRX repositories. It is assumed that a CRX server is running on localhost, and that RMI access is configured on port 1234.

Configuring A Custom JCR Adapter

  • Create the directory c:/toromiro/crx.
  • Toromiro needs a jar (and its dependencies) with a class that can create a javax.jcr.Repository using a method getRepository(String url). In case of CRX, this is the class com.day.crx.rmi.client.CRXClientRepositoryFactory. This can be found in the jar crx-rmi-<version>.jar. Copy this jar and its dependencies to the c:/toromiro/crx folder. All required jars should be located within the crx-quickstart folder which is automatically created when you start the CRX server.

For CRX 1.4.2 you need the following jars:

  • crx-api-1.4.2.jar
  • crx-commons-1.4.2.jar
  • crx-rmi-1.4.2.jar
  • jackrabbit-api-1.4.jar
  • jackrabbit-jcr-commons-1.4.2.jar
  • jackrabbit-jcr-rmi-1.4.1.jar
  • log4j-1.2.14.jar
  • slf4j-api-1.3.0.jar
  • slf4j-log4j12-1.3.0.jar

For CRX 2.2 you need the following jars:

  • crx-shared.jar
  • crx-commons-2.2.0.jar
  • crx-rmi-2.2.0.jar
  • jackrabbit-api-2.2.4.jar
  • jackrabbit-jcr-commons-2.2.4.jar
  • jackrabbit-jcr-rmi-2.2.4.jar
  • log4j-1.2.14.jar
  • slf4j-api-1.5.11.jar
  • slf4j-log4j12-1.5.11.jar
  • In Toromiro, select File >> Preferences from the main menu.
  • In the preferences dialog, select the page Toromiro >> Custom JCR Adapters. Click on the Add button on the right.
  • A dialog titles Edit Custom JCR Adapter will pop up. Enter the following data:
  • Name: CRX
  • Jar Folder: c:/toromiro/crx
  • Client Repository Factory Class: com.day.crx.rmi.client.CRXClientRepositoryFactory
  • URL Client Repository Class: <leave empty>
  • Click on OK to close the dialogs.

The following image shows the custom adapter settings:

subshell's Toromiro custom adapter settings

Connect To A CRX Server Using The Custom Adapter

Once you have the custom JCR adapter set up, you can use it in the connection settings. Create a new repository connection with the following details:

  • Name: CRX
  • JCR adapter: CRX
  • This is the name set in the custom JCR adapter dialog.
  • Repository URL: rmi://localhost:1234/crx
  • Username: admin
  • Password: admin
  • Workspace: <leave empty>
  • Observation: Checked

Hippo CMS

Since Toromiro 1.7.0 it is possible to connect to a Hippo CMS repository via RMI. To do so, download and install the Hippo add-on from Toromiro Extension Update Site and create a repository connection with the following data:

  • Name: Hippo CMS
  • JCR adapter: Hippo 7.7
  • Repository URL: rmi://<hippo cms server url>:1099/hipporepository
  • Username: admin
  • Password: admin
  • Workspace: <leave empty>
  • Observation: Checked

Afterwards you are able to connect to the repository and browse or edit its content.

Note that for Hippo 7.8 you have to enable RMI access by setting the context parameter start-remote-server to true in your web.xml (see Hippo 7.8 Repository Deployment Settings for further information)

Updates

Toromiro can look for new versions each time when started and update automatically. To enable/disable automatic updates, these may be switched on/off in the Preferences within the Install/Update > Automatic Updates section. A manual update can be started using Help > Check for Updates from the main menu.

The update URL for the default product is: http://toromiro.subshell.com/subshell-update/defaultproduct/

Proxy Settings

A Proxy can be configured in the Preferences within the Network Connections section. Restarting the application afterwards is recommended.

Add-ons

There are several add-ons available for Toromiro. To install add-ons use Help > Install New Software... from the main menu and select the Toromiro Extensions Update Site.

The update URL for Toromiro add-ons is: http://toromiro.subshell.com/subshell-update/extendedproduct/

Available Add-ons

  • Sophora Add-on: This is a special Sophora Feature for users of the Sophora content management system. This add-on adds search support for documents via Sophora ID, External ID and Childnode ID to the Repository Search view.
  • ModeShape Add-on: This add-on provides ModeShape JCR adapters for connecting to ModeShape repositories. (Since Toromiro 1.6.0)
  • Hippo Add-on: This add-on provides Hippo CMS adapters for connecting to Hippo repositories. (Since Toromiro 1.7.0)

Trouble Shooting

(Automatic) Update does not work

Fixed. Please reinstall Toromiro 1.6.1 or newer.

Problem: The update aborts with the following message:

'Update' has encountered a problem.
 An error occurred while collecting items to be installed
 session context was:(profile=profile, 
 phase=org.eclipse.equinox.internal.provisional.p2.engine.phases.Collect, 
 operand=, action=).
...

This can be fixed using the following steps:

  • Open the preferences by File > Preferences.
  • Switch to the page Install/Update > Available Software Sites.
  • Edit the software sites "Toromiro Update Site" and "Toromiro Extensions Update Site":
  • Remove the last "/" from the given location and confirm the dialog with OK.
  • Important: Press "Test Connection". This should finish successfully.
  • Close the preferences with OK.
  • Manually start the update by selecting Help > Check for Updates from the main menu.

Installation of Add-ons fails after download on Mac OS X

Fixed. Please reinstall Toromiro 1.6.1 or newer.

Problem: The installation aborts with an error dialog and the following log file entries:

java.lang.IllegalStateException: !fwConfigLocation.equals(fwPersistentDataLocation) !fwConfigLocation=/Users/<username>/Desktop/Toromiro/configuration ,fwPersistentDataLocation=/Users/<username>/Desktop/Toromiro/Toromiro.app/Contents/MacOS/configuration at org.eclipse.equinox.internal.frameworkadmin.equinox.EquinoxManipulatorImpl.checkConsistencyOfFwConfigLocAndFwPersistentDataLoc(EquinoxManipulatorImpl.java:65) at org.eclipse.equinox.internal.frameworkadmin.equinox.EquinoxManipulatorImpl.loadWithoutFwPersistentData(EquinoxManipulatorImpl.java:360) at org.eclipse.equinox.internal.frameworkadmin.equinox.EquinoxManipulatorImpl.load(EquinoxManipulatorImpl.java:331)
[...]
java.lang.IllegalStateException: Error while loading manipulator. at org.eclipse.equinox.internal.p2.touchpoint.eclipse.LazyManipulator.loadDelegate(LazyManipulator.java:54) at org.eclipse.equinox.internal.p2.touchpoint.eclipse.LazyManipulator.getConfigData(LazyManipulator.java:108) at org.eclipse.equinox.internal.p2.touchpoint.eclipse.actions.InstallBundleAction.installBundle(InstallBundleAction.java:76) at org.eclipse.equinox.internal.p2.touchpoint.eclipse.actions.InstallBundleAction.execute(InstallBundleAction.java:29)
[...]

This can be fixed by adding the following lines to the top of the Toromiro/Toromiro.app/Contents/MacOS/toromiro.ini file:

Mac OS X Carbon 32 bit

-startup../../../plugins/org.eclipse.equinox.launcher_1.0.201.R35x_v20090715.jar--launcher.library../../../plugins/org.eclipse.equinox.launcher.carbon.macosx_1.0.200.v20090520-1835

Mac OS X Cocoa 32bit

-startup../../../plugins/org.eclipse.equinox.launcher_1.0.201.R35x_v20090715.jar--launcher.library../../../plugins/org.eclipse.equinox.launcher.cocoa.macosx_1.0.1.R35x_v20090707

Mac OS X Cocoa 64bit

-startup../../../plugins/org.eclipse.equinox.launcher_1.0.201.R35x_v20090715.jar--launcher.library../../../plugins/org.eclipse.equinox.launcher.cocoa.macosx.x86_64_1.0.1.R35x_v20090707

User Guide

The full User Guide for further information about using Toromiro is available in Toromiro's main menu via Help > Help Contents. There is also a Dynamic Help available (via help menu or by pressing F1), that displays help topics about the current view, editor, or wizard you have selected. The User Guide can be downloaded here, too:

Free Trial: Download Toromiro JCR Browser & Editor

Download a fully functional version of Toromiro and a free 30-day trial license now. more

What's new in Toromiro JCR Browser and Editor?

Check out what’s new about the latest released version of Toromiro. 1.12: Updated adapters for ModeShape, several bug fixes and improvements. more

Order Toromiro JCR Browser & Editor Now

Order a registration key for your copy of Toromiro. more

Documentation for Toromiro JCR Browser and Editor

Technical Documentation for subshell's Toromiro JCR Browser and Editor including adapters for Sophora CMS, Magnolia CMS, Adobe CRX, and Hippo CMS. more