Debugging Alfresco #1 – Eclipse JavaScript Debugger und Alfresco Repository

Das Debuggen von Alfresco ist nicht immer ein einfaches Spiel. Die Java Bestandteile können mit den jeweiligen Remote Debugger der gängigen IDEs im laufenden System untersucht werden. Bei JavaScript und FreeMarker Templates stellt sich die Sache schon etwas komplizierter dar.

Während die in Alfresco verbaute Rhino Engine mit einem eigenen, embedded Debugger daher kommt, gibt es für FreeMarker aktuell – zumindest meines Wissens – kein Tooling. Aber auch der embedded Rhino Debugger ist alles andere als handlich. Zum Einen stellt er für Entwickler einen Bruch in einer schon umfangreichen Ansammlung von Tools dar und zum Anderen kann er nur auf Servern mit graphischer Oberfläche eingesetzt werden – ein Debugging einer Entwicklungs- / Testumgebung auf einem Blech oder einer einfachen Server VM ist somit nicht möglich. Ich habe mir daher zuletzt etwas Zeit genommen, die neuen JavaScript Debugger Features des Eclipse JavaScript Development Tools (JSDT) Projekts auszuprobieren.

Seit Version 3.7 der Eclipse IDE sind die notwendigen Bestandteile des JSDT in jeder Distribution enthalten, die das Web Standard Tools Sub-Projekt mitliefert. Nach anfänglichen Problemen aufgrund der noch jungen Debugger Komponente bin ich bei meinen Tests schnell beim aktuellen Milestone 4 des Juno Releases gelandet. Das Wiki des Projekts enthält eine recht nützliche Anleitung zur Verwendung des Rhino Debugger Supports als auch zu unserem speziellen Anwendungsfall der Integration in eine embedded Rhino Engine. Ein kleines FAQ zu den häufigsten Problemen gibt es natürlich ebenfalls.

Damit man mit Eclipse remote den JavaScript Code von Web Scripten und Co debuggen kann, muss im Alfresco Server eine entsprechende Debugger-Komponente laufen und über eine TCP Schnittstelle angesprochen werden können (vgl. der Java Platform Debugger Architecture). Die notwendigen JARs liefert das JSDT gleich als Teil seiner Plugins mit, sodass diese “nur noch” in das <tomcat>/webapps/alfresco/WEB-INF/lib Verzeichnis kopiert werden müssen (wegen einer Class-Abhängigkeit auf die Rhino Engine ist <tomcat>/shared/lib nicht möglich). Die notwendigen Bibliotheken sind:

  • org.eclipse.wst.jsdt.debug.rhino.debugger_<version>.jar
  • org.eclipse.wst.jsdt.debug.transport_<version>.jar

Entsprechend der Anleitung zum Embedden müssen wir den Debugger an den Rhino Context binden und aktivieren. Dazu reicht es, eine kleine Bean zu implementieren und durch Spring beim Bootstrap der Alfresco Webapplikation ausführen zu lassen.

package com.prodyna.debug.rhino;
 
import java.text.MessageFormat;
 
import org.eclipse.wst.jsdt.debug.rhino.debugger.RhinoDebugger;
import org.mozilla.javascript.ContextFactory;
import org.springframework.beans.factory.InitializingBean;
 
public class RemoteJSDebugInitiator implements InitializingBean {
 
	private static final int DEFAULT_PORT = 9000;
	private static final String DEFAULT_TRANSPORT = "socket";
 
	private boolean suspend = false; // suspend until debugger attaches itself
	private boolean trace = false; // trace-log the debug agent
	private int port = DEFAULT_PORT;
	private String transport = DEFAULT_TRANSPORT;
 
	// the global context factory used by Alfresco
	private ContextFactory contextFactory = ContextFactory.getGlobal();
 
	public void afterPropertiesSet() throws Exception {
		// setup debugger based on configuration
		final String configString = MessageFormat.format(
			"transport={0},suspend={1},address={2},trace={3}",
			new Object[] { this.transport, this.suspend ? "y" : "n",
				String.valueOf(this.port), this.trace ? "y" : "n" });
		final RhinoDebugger debugger = new RhinoDebugger(configString);
		this.contextFactory.addListener(debugger);
		debugger.start();
	}
 
	public void setSuspend(boolean suspend) { this.suspend = suspend; }
	public void setTrace(boolean trace) { this.trace = trace; }
	public void setPort(int port) { this.port = port; }
	public void setTransport(String transport) { this.transport = transport; }
	public void setContextFactory(ContextFactory contextFactory) { this.contextFactory = contextFactory; }
}

Diese Bean kann dann durch folgende Beandeklaration in der <tomcat>/shared/classes/alfresco/extension/dev-context.xml aktiviert werden.

<bean id="pd.jsRemoveDebugger" class="com.prodyna.debug.rhino.RemoteJSDebugInitiator">
	<property name="port"><value>8000</value></property>
	<property name="trace"><value>true</value></property>
</bean>

Nach dem Neustart des Alfresco Repository Servers kann man sich mit Eclipse via Remote JavaScript Debugging auf die Rhino Engine aufschalten. Hierzu muss lediglich die entsprechende Debug Configuration angelegt werden, bei der die verwendeten Parameter der Serverkomponente einzutragen sind.

Leider ist damit noch nicht alles getan, um erfolgreich serverseitiges JavaScript aus Eclipse heraus debuggen zu können. Ähnlich wie der Classpath müssen Skripte im Eclipse in einer bestimmten Struktur liegen, damit sie mit den auf den Server ausgeführten Skripten abgeglichen werden können. Nur wenn dieser Abgleich erfolgt ist, werden Breakpoints, die in JavaScript Dateien ähnlich wie in Java mit einem Doppelklick auf den sog. Ruler eingestellt werden, von Eclipse an den Server übermittelt und aktiviert.

Die notwendige Source Code Struktur für remote debuggte Skripte richtet sich nach dem bei der Übergabe an die Rhino Engine angegebenen Source Namen. Alfresco verwendet hier durchgehen die File URI des Hauptskripts, d.h. also für einen Repository Server, welcher in “D:\Applications\Swift\tomcat” deployed wurde, beträgt die URI für den Web Script Controller sites.get.js “file://D:/Applications/Swift/tomcat/webapps/alfresco/WEB-INF/classes/alfresco/templates/webscripts/org/alfresco/repository/sites/sites.get.js”. Laut dem FAQ des JSDT wird eine solche URI ohne den “file://D:/” Prefix auf ein automatisch angelegtes Source Projekt “External JavaScript Source” gemapped. Dies traf bei mir nicht zu und nach Studium des Source Code des JSDT Plugins habe ich eine funktionierende Alternative gefunden: das erste Pfadelement entspricht einem Source Projekt und der Rest des Pfades ist relativ zu diesem zu betrachten. Um also JavaScript Web Script Controller in meinem Swift Repository debuggen zu können, musste ich dessen Web Scripte in einem Projekt namens “Applications” in einer Ordnerstruktur “Swift/t/tomcat/webapps/alfresco/WEB-INF/classes/alfresco/templates/webscripts/” zur Verfügung stellen. Am einfachsten geht dies, indem man den Source Code des Alfresco Remote API Projekts als Source in eine solche Struktur linkt.

Nachdem diese letzte Konfiguration abgeschlossen wurde, werden Breakpoints, die in Alfresco Web Script, wie z.B. sites.get.js gesetzt wurden, sauber an den Server übertragen. Bei der nächsten Ausführung einer Site Suche in Alfresco Share hält der Debugger dann entsprechend an der definierten Position an und lässt das Web Script mit den gewohnten Funktionen wie Step Over / Into, der Variables sowie Expressions View untersuchen. Besonders letztere ist aktuell noch übermäßig wertvoll, da der Debugger mit Java Objekten als Variablenwerte in der Variables View nicht viel anfangen kann.

Zwischenfazit: Mit dem Eclipse JSDT lassen sich JavaScript Dateien, die Teil der Alfresco Applikation – d.h. dessen Classpath – sind, aus der gewohnten Entwicklungsumgebung heraus remote debuggen. Damit entfällt die bisherige Einschränkung des Rhino Debuggers, dass JavaScript Dateien nur auf lokalen Servern bzw. Servern mit graphischer Oberfläche debug-bar sind. Die Einrichtung des JSDT Remote Debuggers mag etwas gewöhnungsbedürftig sein, ist jedoch mit den zur Verfügung stehenden Mitteln des Source Linkings  schnell und ohne unnötige Code Redundanz im Workspace realisierbar. Aktuell gibt es aufgrund des noch jungen Debuggers und der Art und Weise, wie Alfresco die Rhino Engine integriert hat, ein paar Besonderheiten und Einschränkungen in der Nutzung des Debuggers. Auf diese werden ich in kommenden Posts dieser Serie eingehen und – soweit möglich – Lösungen vorstellen.

Kommentar schreiben

6 Kommentare.

  1. Hallo Herr Faust,

    danke für diesen Beitrag! Ich würde vorschlagen, diesen Beitrag direkt an Alfresco weiterzuleiten, so dass der Debugging-Support Standard in Alfresco 4.x werden kann und z.B. per einfacher Konfiguration und Kopieren der Eclipse-Bibliotheken aktiviert werden kann.

    Danke und viele Grüße,
    Jens Goldhammer

  2. Hallo Axel,

    the rhino embedded debugger definitely has its drawbacks, and uniform debugging even providing more features !) surely is something we should aim at.

    This is all pretty much bleeding edge today. Thats fine with me in general, although I don’t want to try eclipse milestones or snapshots for day to day work.

    I really appreciate reading your experiences, and I’m curious how this will all work out.

    I see a few hurdles ahead before this can go “mainstream”.

    Debugging (rhino) server side javascript in the alfresco world applies to surf apps (such as share) as well. Should not be a big deal getting this all to work in the surf environment I guess.

    I don’t know much about the debugging protocol used and how it depends on rhino or eclipse. Not everybody is using eclipse (I do), and alfresco may choose to replace rhino with nashorn one day.

    cheers
    Andreas

    • Hi Andreas,

      I agree, Milestones / Snapshots are not practical for regular usage – but the stable Juno will be released in June this year so this will be available to the general developer pretty soon. This is my current pet project and I will be looking into expanding this to the Surf layer as well as providing an alternative import mechanism for JavaScript – the current one produces a ton of syntax errors and scripts using it can effectively not be properly debugged.

      The debug transport protocol is a generic JSON based-format that is not dependant on Rhino or Eclipse. Should Alfresco switch to Nashorn – and I figure this is yet a very long way in the future (when JDK 8 actually has become the major version used in production by customers) – only the adapter to the engine should need to change. But I’d assume before other IDEs reuse the transport protocol and engine adapter of Eclipse, they’d be developing their own.

      Regards, Axel

      • Hi Axel,

        please replace the import “tag” with a library call.

        In fact, this is bugging me far more than the embedded debugger. ;)

        You may want to have a look at:

        http://code.google.com/p/share-extras/issues/detail?id=64
        http://stackoverflow.com/questions/8124906/alfresco-debugger-cannot-open-js-including-an-import-tag/8799964

        cheers
        Andreas

      • Hi Axel, the import syntax is something I also looked into recently with the Javascript Console. You would have to overwrite the whole RhinoScriptProcessor to change the import, since the actual String replacement is done in a static helper :(

        I think it’s best to use a simple node.js style require(“somescript.js”) command and parse it the same way as the current xml import statements are parsed before script compilation.

        To have support for AMD (https://github.com/amdjs/amdjs-api/wiki/AMD) style module definitions would be nice but I don’t think it’s practical with the way scripts are executed in Alfresco.

        • Hi Florian,

          having a API library function is what I am aiming for too. In my first approach I dove into the RhinoScriptProcessor and changed the way import-tags are handled, the two major changes being that scripts would no longer be merged but simply executed in sequence and the import tag could be in a line comment at the start of the file, thus no longer messing up syntax validation. The changes were actually not that extensive as I first believed they would be. We’ll see how much hassle implementing a library function entails – I hope to get around to doing this within the next two weeks…

Antwort an Florian Maul ¬
Antwort abbrechen


Hinweis - Du kannst dies benutzenHTML tags and attributes:
<a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>