Archiv nach Kategorien: Alfresco

Alfresco mit Arquillian #1 – “Managed Tomcat”

Veröffentlicht von am Juli 7, 2013 Keine Kommentare

Hinweis: Das Editor / Code Formatter Plugin wandelt leider einige XML-Tags in eine falsche Schreibweise um. Bei Übernahme der Beispiele sind daher die betroffenen Tags zu korrigieren (u.a. dependencyManagement, groupId, artifactId, activeByDefault, systemPropertyVariables, containerProfile, arquillian.launch).

Content Repositories sind komplexe und zentrale Komponenten einer IT Infrastruktur / Content Management Lösung. Dies zieht entsprechend hohe Ansprüche im Punkt Qualitätsmanagement nach sich. Bei Alfresco Entwicklungsprojekten wird überwiegend JUnit eingesetzt um Entwicklertests zu realisieren. Das Alfresco Repository kann dabei innerhalb eines einfachen JUnit-TestCase eines fachlichen Moduls durch die Alfresco-Klasse ApplicationContextHelper im gleichen Prozess gestartet oder in einem eingebetteten Container (z.B. Jetty im Rahmen eines Maven-Builds) betrieben werden. Dabei werden in der Regel individuelle fachliche Komponenten nur isoliert und in einem von einer realistischen Umgebung stark abweichenden Konfiguration (u.a. mit umfangreichen Mocks) getestet. Dies kann dazu führen, dass eine hohe Codeabdeckung und Erfolgsquote von Tests nur eingeschränkt aussagekräftig für die Qualität eines Projekts sind und ein böses Erwachen in dedizierten Test- / Abnahmeumgebungen droht.

Im Rahmen unserer Tätigkeit als Alfresco Partner beschäftige ich mich in meiner verfügbaren Zeit außerhalb von Projekten und Vertrieb unter anderem damit, für Entwickler- und Integrationstests Alfresco mit dem auf JUnit basierenden Framework Arquillian zusammen zu bringen. Die verschiedenen Aspekte, Probleme und Ansätze werde ich versuchen, in spezfischen Posts zusammen zu fassen.

Probleme mit “Embedded Tomcat” Setup

Für viele Entwicklungsprojekte mag ein “Embedded” Setup für die Durchführung von lokalen Tests die einfachste Konfiguration darstellen – sowohl in Bezug auf Unabhängigkeit der Konfiguration vom jeweiligen Setup der Entwickler als auch auf die Roundtrip-Zeit der Testdurchführung. Zusammen mit meinen Kollegen habe ich versucht, ein “Embedded Tomcat” Setup mit Arquillian zusammen zu stellen. Es ist jedoch nicht gelungen, die diversen Classloading Probleme, welche sich bei einer Ausführung von Tomcat im gleichen Prozess ergaben, aufzulösen. Speziell mit diversen XML-APIs, welche sowohl im Tomcat als auch im JDK enthalten sind und von Alfresco referenziert werden, kam es zu großen Inkompatibilitäten zwischen dem Arquillian / Maven / Boot-Classloader und dem Classloader für die Alfresco Webapplikation.

Vorbereitungen Tomcat-Instanz / globale Alfresco Konfiguration

Für die Durchführung von Test in einem “Managed Tomcat” Instanz muss eine lokale Tomcat-Instanz bereitgestellt werden, welche Arquillian zur Laufzeit der Tests anspricht und darauf das Alfresco Repository WAR deployed. Entsprechend der zu testenden Alfrescoversion kommt hier entweder Tomcat 6 oder 7 zum Einsatz. Es ist empfehlenswert, einen eigene Tomcat-Instanz für Arquillian aufzusetzen und nicht den ggf. mit dem Alfresco Installer installierten Tomcat zu verwenden.

Damit Arquilian Alfresco nach dem Start des Tomcat auch auf diesen deployen kann, ist es notwendig, die “Manager” Webanwendung von Tomcat auf diesem bereit zu stellen und eine entsprechende Konfiguration der tomcat-users.xml vorzunehmen. Alle anderen Webanwendungen, welche von Tomcat ausgeliefert werden (ROOT / host-manager o.ä.) können bedenkenlos entfernt werden. Eine einfache Konfiguration der tomcat-users.xml kannwie folgt aussehen:

< ?xml version='1.0' encoding='utf-8'?>
<tomcat -users>
  <role rolename="manager"/>
  <user username="arquillian" password="arquillian" roles="manager"/>
</tomcat>

Um die Testfälle möglichst frei von umgebungsspezifischer Konfiguration zu halten sollte innerhalb der Tomcatinstanz eine alfresco-global.properties mit einer funktionsfähigen Grundkonfiguration sowie die notwendigen Datenbanktreiber bereitgestellt werden. Diese sind wie gewohnt unter <tomcat>/shared/classes abzulegen. Die Konfiguration der Datenbankanbindung, Ablage von Dokumentinhalten sowie unterstützender Komponenten ist hier vorrangig, allerdings können auch Subsysteme (vor-)konfiguriert werden. Für wahrscheinlich 80 % der Testfälle treffen folgende Grundeinstellungen zu:

  • Subsystem “fileServers”: Deaktivierung von CIFS, NFS und FTP (über JUnit i.d.R. nicht getestet)
  • Subsystem “email”: Deaktivierung des IMAP / SMTP Servers (über JUnit i.d.R. nicht getestet)

Wird die Subsystemkonfiguration über die korrekte Vorgehensweise, d.h. unter Verwendung von <tomcat>/shared/classes/alfresco/extension/subsystems/<Subsystem>/… durchgeführt, können die Voreinstellungen bei Bedarf in einzelnen Testfällen unter Ausnutzung des ClassLoader-Verhaltens überschrieben werden. Unter keinen Umständen sollte Subsystemkonfigurationen daher in alfresco-global.properties durchgeführt werden (auch unabhängig von Arquillian eher “Bad Practice”).

Projektsetup

Die Einbindung von Arquillian in ein bestimmtes Entwicklungsprojekt kann sehr individuell erfolgen. Zu Demonstrationszwecken dient ein einfaches Maven Java-Projekt als Grundlage der weiteren Ausführungen. Die Integration mit dem Alfresco Maven SDK ist dem geneigten Leser überlassen.
Mit mvn archetype:generate -DgroupId={project-packaging} -DartifactId={project-name} -DarchetypeArtifactId=maven-archetype-quickstart -DinteractiveMode=false oder dem entsprechenden Wizard-Äquivalent der IDE lässt sich ein einfaches Projekt erstellen. Um Arquillian für den Anwendungsfall von Alfrescotests im Maven Lifecycle zu integrieren, sollte folgende Dependency-Konfiguration vorgenommen werden:

    <repositories>
        <repository>
            <id>jboss-public-repository</id>
            <name>JBoss Public Repository</name>
            <url>https://repository.jboss.org/nexus/content/groups/public</url>
        </repository>
    </repositories>
 
    <dependencymanagement>
        <dependencies>
            <dependency>
                <groupid>org.jboss.arquillian</groupid>
                <artifactid>arquillian-bom</artifactid>
                <version>1.0.4.Final</version>
                <scope>import</scope>
                <type>pom</type>
            </dependency>
        </dependencies>
    </dependencymanagement>
    <dependencies>
        <dependency>
            <groupid>junit</groupid>
            <artifactid>junit</artifactid>
            <version>4.8.1</version>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupid>org.jboss.arquillian.junit</groupid>
            <artifactid>arquillian-junit-container</artifactid>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupid>org.jboss.arquillian.extension</groupid>
            <artifactid>arquillian-service-integration-spring-inject</artifactid>
            <version>1.0.0.Beta1</version>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupid>org.jboss.arquillian.extension</groupid>
            <artifactid>arquillian-service-deployer-spring-3</artifactid>
            <version>1.0.0.Beta1</version>
            <scope>test</scope>
        </dependency>
        <dependency>
            <groupid>org.jboss.shrinkwrap.resolver</groupid>
            <artifactid>shrinkwrap-resolver-impl-maven</artifactid>
            <scope>test</scope>
        </dependency>
    </dependencies>

Diese Abhängigkeiten bilden die Grundlage für das im Arquillian Test-Lifecycle notwendige Zusammenbauen des Alfresco Deployments über die ShrinkWrap API sowie den Zugriff auf Beans des Alfresco Repository für eingebettete JUnit-Tests. Die Spring-bezogenen Abhängigkeiten können weggelassen werden, falls Arquillian ausschließlich für Remote-Tests verwendet werden soll.

Die Verwendung eines von Arquillian gesteuerten Tomcats bedarf der Erstellung des folgenden Profils:

    <profiles>
        <profile>
            <id>tomcat-managed</id>
            <activation>
                <activebydefault>true</activebydefault>
            </activation>
            <dependencymanagement>
                <dependencies>
                    <!-- Lock the version, since additional dependencies (i.e. from Alfresco) often clash -->
                    <dependency>
                        <groupid>commons-codec</groupid>
                        <artifactid>commons-codec</artifactid>
                        <version>1.5</version>
                    </dependency>
                </dependencies>
            </dependencymanagement>
            <dependencies>
                <dependency>
                    <groupid>org.jboss.arquillian.container</groupid>
                    <artifactid>arquillian-tomcat-managed-6</artifactid>
                    <version>1.0.0.CR4</version>
                    <scope>test</scope>
                </dependency>
            </dependencies>
        </profile>
    </profiles>

Für Tests von Alfresco 4.2 mit Tomcat 7 ist die entsprechend alternative Abhängigkeit arquillian-tomcat-managed-7 zu verwenden.

Die zu verwendende Tomcat-Instanz ist über eine arquillian.xml innerhalb des Classpaths des Projekts zu konfigurieren. Diese Datei kann z.B. unter src/test/resources abgelegt werden, um eine globale Konfiguration für das gesamte Projekt zu liefern, oder ein einem Profil-spezifischen Pfad, um individuelle Konfigurationen je nach aktuellem Entwickler zu realisieren. Eine Profil-spezifische Ablage der Datei ist an sich grundsätzlich nicht notwendig, da sich die verschiedenen Konfigurationen innerhalb dieser Datei durch eine Konfiguration des Surefire Plugins individuell ansprechen lassen. Eine Grundkonfiguration er arquillian.xml kann wie folgt aussehen:

< ?xml version="1.0" encoding="UTF-8"?>
<arquillian xmlns="http://jboss.org/schema/arquillian" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://jboss.org/schema/arquillian http://jboss.org/schema/arquillian/arquillian_1_0.xsd" xmlns:spring="urn:arq:org.jboss.arquillian.container.spring.embedded_3">
    <container qualifier="tomcat-managed-6" default="true">
        <configuration>
            <!-- Must match HTTP port from Tomcat server configuration file -->
            <property name="bindHttpPort">8680</property>
            <property name="bindAddress">localhost</property>
            <!-- The prepared Tomcat instance -->
            <property name="catalinaHome">D:/Applications/Arquillian/tomcat-repo</property>
            <property name="javaHome">C:/Program Files/Java/jdk1.6.0_30</property>
            <!-- Allow generous Heap and PermGen since we may deploy + start Alfresco multiple times -->
            <property name="javaVmArguments">-Xmx2G -Xms2G -XX:MaxPermSize=1G -Dnet.sf.ehcache.skipUpdateCheck=true -Dorg.terracotta.quartz.skipUpdateCheck=true</property>
            <!-- Must match configured manager from tomcat-users.xml -->
            <property name="user">arquillian</property>
            <property name="pass">arquillian</property>
            <property name="urlCharset">UTF-8</property>
            <property name="startupTimeoutInSeconds">120</property>
            <!-- Local copy of Tomcat server configuration file -->
            <property name="serverConfig">server.xml</property>
        </configuration>
    </container>
 
    <extension qualifier="spring">
        <!-- Deactive automatic inclusion of Spring artifacts in deployments as Alfresco already contains them -->
        <property name="auto-package">false</property>
    </extension>
</arquillian>

Die notwendige server.xml kann aus der konfigurierten Tomcatinstanz in den Classpath des Projekts (src/test/resources) kopiert werden. Aus noch nicht nachvollzogenen Gründen kann hier keine Pfadangabe auf die Datei innerhalb der Tomcatinstanz verwendet werden.

Der Wert des qualifier-Attributs der container-Konfiguration kann wie folgt zum Selektieren eines speifischen Profils aus der POM heraus verwendet werden:

<build>
    <plugins>
        <plugin>
            <groupid>org.apache.maven.plugins</groupid>
            <artifactid>maven-surefire-plugin</artifactid>
            <configuration>
                <systempropertyvariables>
                    <arquillian .launch>${containerProfile}</arquillian>
                </systempropertyvariables>
            </configuration>
        </plugin>
    </plugins>
</build>
<profiles>
    <profile>
        <id>Dev XY</id>
        <properties>
            <containerprofile>xy-tomcat-managed-6</containerprofile>
        </properties>
    </profile>
</profiles>

Bei Verwendung der JUnit-Integration in Eclipse ist entsprechend der -Darquillian.launch Parameter in der Startkonfiguration zu setzen.

Ein einfacher REST API Test

Die einfachste Verwendung, welche sich mit Arquillian ohne größere Anpassungen realisieren lässt, sind Tests der REST API von Alfresco. Folgender TestCase kann mit der bisherigen Konfiguration (zzgl. Abhängigkeiten auf org.jboss.resteasy:resteasy-jaxrs und org.json:json) direkt ausgeführt werden:

@RunWith(Arquillian.class)
public class SimpleLoginRemoteTest {
    @ArquillianResource // HTTP base-URl specific for our test deployment
    private URL baseURL;
 
    @Deployment // build the Repository WAR we want to test
    public static WebArchive createDeployment() throws Exception {
        // initialize Maven resolver from our project POM (specifically: repository-configuration to retrieve artifacts)
        final MavenDependencyResolver resolver = DependencyResolvers.use(MavenDependencyResolver.class).loadMetadataFromPom("pom.xml");
 
        // we want a standard Alfresco WAR for our tests - no modifications
        final File[] files = resolver.artifact("org.alfresco.enterprise:alfresco:war:4.1.4").exclusion("*:*").resolveAsFiles();
 
        // there is a simpler "createFromZipFile" method, but we want to provide a custom webapp-name to avoid deployment conflicts
        // files[0] is the resolved alfresco.war
        final WebArchive webArchive = ShrinkWrap.create(WebArchive.class, "SimpleLoginRemoteTest.war").as(ZipImporter.class).importFrom(files[0]).as(WebArchive.class);
        return webArchive;
    }
 
    @RunAsClient @Test
    public void testAdminRESTLogin() throws Exception {
        // use JBoss resteasy-library + org.json (add to POM) to perform a login
        final ClientRequest loginRequest = new ClientRequest(this.baseURL.toURI() + "s/api/login");
        loginRequest.accept("application/json");
 
        final JSONObject loginReqObj = new JSONObject();
        loginReqObj.put("username", "admin").put("password", "admin");
 
        loginRequest.body("application/json", loginReqObj.toString());
 
        final ClientResponse< String> loginResponse = loginRequest.post(String.class);
        Assert.assertEquals("Login failed", 200, loginResponse.getStatus());
    }
}

Erläuterungen zum Beispiel:

  • Arquillian-spezifische TestCase-Klassen müssen mit einem entsprechenden Arquillian-Runner ausgeführt werden, welcher den Lifecycle des TestCase abweichend vom JUnit-Standard steuert.
  • Pro TestCase gibt es eine statische Methode mit @Deployment Annotation, welche das zu testende Artefakt über ShrinkWrap erstellt. Hier können die notwendigen bzw. zu testenden Teilkomponenten individuell zusammengeführt werden.
  • Testmethoden mit @RunAsClient Annotation werden von Arquillian innerhalb des JUnit-Prozesses / -Kontext ausgeführt und haben können keinen direkten Zugriff auf Beans des Alfresco Repository nehmen. Fehlt diese Annotation, wird die jeweilige Testmethode über ein automatisch von Arquillian in das WebArchive eingefügtes ArquillianServletRunner-Servlet innerhalb der Alfresco Repository Webanwendung ausgeführt.
  • Für Testmethoden, welche via @RunAsClient remote auf das Alfresco Repository zugreifen müssen, wird über ein mit @ArquillianResource annotiertes URL Instanzfeld die HTTP URL für den Kontext der Webanwendung bereitgestellt.
  • Bei Verwendung des MavenDependencyResolver auf Basis der Projekt-POM müssen die notwendigen Repositories für Alfresco-Artefakte (z.B. http://artifacts.alfresco.com/…) in der POM eingetragen werden.

Bei der Ausführung über die JUnit-Integration der IDE oder mvn test startet Arquillian die Tomcatinstanz, baut über die entsprechende Callback-Methode das zu testende Artefakte zusammen und überträgt/startet dieses über die Tomcat Manager Webanwendung. Sofern die Tomcatinstanz konfiguriert wurde, sollte entweder ein grüner Balken im JUnit-Fenster oder ein BUILD SUCCESS auf der Maven Konsole erscheinen.

Ein einfacher (Service-)Bean Test

Sollen mit Arquillian individuelle (Service-)Beans getestet werden muss eine Testklasse direkt auf den Spring-Kontext der Alfresco Repository Webanwendung zugreifen. Entegegen den regulären Alfresco JUnit-Tests (z.B. NodeServiceTest) kann dies nicht über den ApplicationContextHelper erfolgen. Da aufgrund der Mischung von regulären Testmethoden und @RunAsClient-Methoden in einer Klasse dies Klasse in zwei unterschiedlichen Kontexten laufen kann, ist es auch nicht ohne weiteres (sauber) möglich, in einer @Before/@BeforeClass und mithilfe ContextLoader.getCurrentWebApplicationContext() auf den Spring-Kontext zuzugreifen um notwendige Beans zu ermitteln. Mit einer einfachen Anpassung an der Erstellung des Deployments und unter Verwendung der @Autowired sowie @Qualifier Annotationen kann man sich die benötigten Beans durch den ArquillianServletRunner bereitstellen lassen.

@RunWith(Arquillian.class) @SpringWebConfiguration
public class SimpleNodeServiceLocalTest {
    @Deployment
    public static WebArchive createDeployment() {
        final MavenDependencyResolver resolver = DependencyResolvers.use(MavenDependencyResolver.class).loadMetadataFromPom("pom.xml");
 
        final File[] files = resolver.artifact("org.alfresco.enterprise:alfresco:war:4.1.4").exclusion("*:*").resolveAsFiles();
        final WebArchive webArchive = ShrinkWrap.create(WebArchive.class, "SimpleNodeServiceLocalTest.war").as(ZipImporter.class).importFrom(files[0]).as(WebArchive.class);
        webArchive.addAsResource("arquillian-alfresco-context.xml", "alfresco/extension/arquillian-alfresco-context.xml");
        return webArchive;
    }
 
    @Autowired @Qualifier("NodeService")
    protected NodeService nodeService;
 
    @Autowired @Qualifier("TransactionService")
    protected TransactionService transactionService;
 
    @Test
    public void testNodeService() throws Exception {
        Assert.assertNotNull("NodeService not injected", this.nodeService);
        Assert.assertNotNull("TransactionService not injected", this.transactionService);
 
        AuthenticationUtil.setFullyAuthenticatedUser("admin");
        try {
            this.transactionService.getRetryingTransactionHelper().doInTransaction(new RetryingTransactionCallback< Void>() {
                public Void execute() throws Throwable {
                    final List< StoreRef> stores = SimpleNodeServiceLocalTest.this.nodeService.getStores();
 
                    Assert.assertFalse("List of stores is empty", stores.isEmpty());
 
                    // check default / standard stores
                    Assert.assertTrue("Store workspace://SpacesStore not contained in list of stores", stores.contains(StoreRef.STORE_REF_WORKSPACE_SPACESSTORE));
                    Assert.assertTrue("Store archive://SpacesStore not contained in list of stores", stores.contains(StoreRef.STORE_REF_ARCHIVE_SPACESSTORE));
                    return null;
                }
            }, true);
        } finally {
            AuthenticationUtil.clearCurrentSecurityContext();
        }
    }
}

Die arquillian-alfresco-context.xml zum Beispiel:

< ?xml version='1.0' encoding='UTF-8'?>
<beans xmlns="http://www.springframework.org/schema/beans" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:context="http://www.springframework.org/schema/context"
    xsi:schemaLocation="
            http://www.springframework.org/schema/beans
            http://www.springframework.org/schema/beans/spring-beans-3.0.xsd
            http://www.springframework.org/schema/context
            http://www.springframework.org/schema/context/spring-context-3.0.xsd">
    <context:annotation -config />
</beans>

Erläuterungen zum Beispiel:

  • Über die @SpringWebConfiguration Annotation wird deklariert, dass bei Ausführung des Tests im Container Beans aus dem aktuellen Spring-Kontext der Webanwendung benötigt werden. Sofern Servlets individuelle Kontexte hätten, könnten dieser über einen optionalen Parameter gezielt angesprochen werden.
  • Mit den @Autowired und @Qualifier werden über die Autowiring-Funktionalität von Spring spezifische Beans in die Instanz der Testklasse injeziert, sofern diese im Container ausgeführt wird. Autowiring ist in Alfresco nicht vorkonfiguriert, weswegen im Deployment eine zusätzliche Spring XML Konfigurationsdatei zum WAR hinzugefügt wird. Diese Datei ändert faktisch nichts an der Spring-Konfiguration von Alfresco, aktiviert aber implizit die Unterstützung von Autowiring.
  • Testmethoden laufen grundsätzlich ohne Authentifizierung oder einem Transaktionskontext. Sofern dieser für Tests benötigt wird, muss dieser im Test initiiert werden. Bei Verwendung von öffentlichen Service-Beans (z.B. “NodeService”) kann dieser wegfallen, wenn eine atomare Operation getestet wird, da öffentliche Service-Beans (bei korrekter Konfiguration) automatisch bei einem Aufruf für einen gültigen Transaktionskontext sorgen.
  • In der POM des Projekts ist die Alfresco Repository JAR der entsprechenden Alfresco Version als Abhängigkeit einzutragen, damit der Test kompilieren kann.

Offene Punkte / Probleme

Mit den bereit gestellten Beispielen lässt sich Alfresco allumfänglich in einem “Managed Tomcat” Szenario testen. Allerdings gibt es wie bei allen Testansätzen auch hier diverse Punkte / Probleme, welche die Nutzbarkeit / Effizienz einschränken können. Im folgenden seien die aus meiner Sicht kritischsten Punkte genannt:

  • Dauer des Deployment – Jedes Deployment einer Testfall-spezifischen Alfresco Repository WAR verbaucht eine enorme Zeit für die Übertragung sowie das Hoch- und Runterfahren Teilkomponenten. Auf meinem Lenovo T520 mit einer aktuellen SSD und 16 GiB RAM beläuft sich ein Durchlauf von 2 Testklassen (Komplexität nicht viel höher als die Beispiele hier) auf ca. 3 Minuten. Für einzelne Komponententests mag dies mit einer kleinen Kaffeepause durchaus noch vertragbar sein – für größere bzw. häufige Integrationstests z.B. in einem Continuous Integration Kontext wäre dies aber ein erhebliches Problem.
  • Speicherlast – Das vielfache Durchführen von Deployments in Tomcat erfordert große Mengen an Speicher, speziell für die Permanent Generation. Je nach Ausstattung der Entwicklungsumgebung kann dieser u.U. nicht bereitgestellt werden, sodass nur einzelne / wenige Testfälle in einem Durchgang ausgeführt werden können.
  • Deploymentfehler – Bei mehreren Durchläufen sind in meiner Konstellation Fehler beim (Un-)Deployment der Webanwendungen aufgetreten, welche nur durch manuelle Eingriffe bereinigt werden konnten. Für ein Continuous Integration Szenario ist dies nicht akzeptabel.
  • Kleinere Inkonsistenzen zwischen Tomcat-Versionen – Bei Test von Alfresco 4.2 auf Tomcat 7 wurde durch Arquillian das benötigte ArquillianServlertRunner Servlet nicht automatisch in die web.xml eingefügt. Dadurch konnten keine Tests gegen (Service-)Beans durchgeführt werden. Die (unschöne) Lösung des Problems bestand darin, eine angepasste web.xml mit expliziter Konfiguration des AruillianServletRunner Servlets in das WebArchive zu integrieren.
  • Bereitstellung einer definierten Datenbasis – Für einzelne Tests kann es notwendig sein, dass diese einen definierten Zustand von Daten (Datenbank, Inhalte, Index) vorfinden. Die Datenhaltung erfolgt bei einem “Managed Tomcat” Setup aber außerhalb der Testfalllogik und kann von dieser nicht ohne umgebungspezifischen Code beeinflusst werden.

In weiteren Blog-Posts sollen für einige dieser Punkte mögliche Ansätze / Lösungen beschrieben werden.

Skriptimporte mit sauberer API

Veröffentlicht von am März 12, 2012 2 Kommentare

Update: Der Patch wurde ins Alfresco JIRA übertragen und kann unter ALF-13631 verfolgt werden.

Im Rahmen meiner Bemühungen, mittels Eclipse JSDT Alfresco JavaScript remote zu debuggen, stellte sich die Art und Weise, wie in Alfresco JavaScript andere Skripte importiert werden, als eines der zentralen Probleme heraus. Aktuell wird hier ein Ansatz ähnlich einem Präprozessor verwendet und Skripte erst unmittelbar vor ihrer Ausführung endgültig zusammengefügt. Die für diesen Mechanismus notwendige Importdirektive sieht sowohl im Repository als in Share wie folgt aus:

<import resource="classpath:/alfresco/templates/org/alfresco/import/alfresco-util.js">
/**
 * Main entrypoint
 */
function main()
{
   var activityFeed = getActivities();
   var activities = [], activity, item, summary, fullName, date, sites = {}, siteTitles = {};
   var dateFilter = args.dateFilter, oldestDate = getOldestDate(dateFilter);
   ...
}
main()</import>

Vor der Ausführung wird ein Skript von Beginn an nach import-Tags durchsucht und alle Fragmente zu einer Gesamtdatei zusammen gefügt. Der Prozess stoppt beim ersten Zeichen (Whitespaces ausgenommen), welches nicht Teil eines import-Tags ist. Dieses Vorgehen hat einschränkende Konsequenzen:

  1. Imports an anderen Stellen außer dem Kopf eines Skripts sind nicht möglich.
  2. Dynamische Imports sind nicht möglich, d.h. es können nicht dynamisch im Laufe der Logikausführung Skripte eingebunden werden.
  3. Syntaxprüfungen von IDEs bemängeln die Importsyntax zu Recht als nicht valide.
  4. Rhino Fehlermeldungen zeigen eine Zeilennummer an, die nicht mit dem Quellcode übereinstimmt – man ist häufig gezwungen, über alle Imports manuell und fehleranfällig die echte Zeilennummer in der Originaldatei auszurechnen, um sich besagte Zeile anschauen zu können.
  5. Breakpoints beim Debuggen können nicht vor der Ausführung eines Skripts gesetzt werden. Das trifft meinen Ansatz mit JSDT härter als die mitgelieferten Rhino Debugger UI, da mir im JSDT die aggregierten Dateien zu keinem Zeitpunkt zur Verfügung stehen.

Ich hatte mir schon länger vorgenommen, hier einen alternativen Ansatz zu finden – nicht nur um sinnvolles Debuggen mit JSDT zu ermöglichen, sondern auch auf eine flexiblere Nutzung / Wiederverwendung von Skripten zurück greifen zu können. Dieses Wochenende blieb mir dann auch endlich die ersehnte Zeit, hier aktiv zu werden. Ziel sollte es sein, eine kleine JavaScript API Erweiterung zur Verfügung zu stellen, mit der sich andere Skripte an beliebigen Stellen im Code importieren lassen. Zusätzlich wollte ich es ermöglichen, dass der Skript-Lookup Mechanismus einfach durch zusätzliche Lookup-Komponenten erweitert werden kann, ohne in die JavaScript API eingreifen zu müssen.

Alfresco selber bietet mit seinen javaScriptExtension Beans Möglichkeiten, neue Root Objekte in die API zu integrieren. Für mein Vorhaben war dieser Ansatz jedoch nicht ausreichend – die Java-basierten Services, die man über diesen Mechanismus zur Verfügung stellen kann, haben nicht den notwendigen Zugriff auf den Ausführungskontext der Rhino Script Engine. Mit einem Patch des RhinoScriptProcesor dagegen lässt sich eine native JavaScript Funktion einfach im globalen Kontext bekannt machen, die zusätzlich den notwendigen Zugriff auf Interna des Prozessors wie u.A. den ScriptCache hat. Die fertige Importfunktion steht in JavaScript wie folgt zur Verfügung:

importScript("legacy", "classpath:/alfresco/templates/webscripts/org/alfresco/repository/forms/pickerresults.lib.js", true);

Die drei Parameter der Funktion werden wie folgt verwendet:

  1. Die zu verwendende Lookup-Komponente für den Import. Mit “legacy” wird der grundsätzliche Ansatz des alten import-Tags verwendet, sodass sich bestehender Code mit RegEx-basiertem Suchen & Ersetzen schnell anpassen lässt. Weiter habe ich zwei dedizierte Komponenten für “classpath” und “xpath” umgesetzt.
  2. Eine textbasierte Referenz auf ein Skript, welches durch die gewählte Importer-Komponente aufzulösen ist.
  3. Ein Boolean-Parameter, welcher bestimmt, ob der Import bei einem nicht auflösbaren Import mit einer ScriptException fehlschlagen soll.

Die Funktion führt das zu importierende Skript im gleichen Kontext und Scope des Aufrufs aus. Das importierte Skript kann somit auf Variablen und Funktionen des aufrufenden Skripts zugreifen und mit diesen interagieren. Die Funktion hat einen Boolean-Rückgabeparameter, über welchen ein erfolgreich durchgeführter Import geprüft werden kann, wenn ein nicht auflösbarer Import nicht automatisch zu einem Fehlschlag führt. Als JavaScript Funktion kann der Import an jeder beliebigen Stelle eines Skripts erfolgen und bei Verwendung von berechneten Variablen dynamisch beliebige Skripte importieren.

Zusätzliche Import-Komponenten können durch Implementierung eines kleinen Java Interfaces und Verknüpfung mit dem RhinoScriptProcessor zur Verfügung gestellt werden. Das Interface definiert dabei nur eine Methode zum Auflösen des Referenzparameters. Mit einem zusätzlichen Kontextparameter für den Ablageort des aktuell ausgeführten Skripts lassen sich auch relative Referenzen realisieren.

public interface ScriptLocator {
 
	/**
	 * Resolves a string-based script location to a wrapper instance of the
	 * {@link ScriptLocation} interface usable by the repository's script
	 * processor. Implementations may support relative script resolution - a
	 * reference location is provided in instances an already running script
	 * attempts to import another.
	 *
	 * @param referenceLocation
	 *            a reference script location if a script currently in execution
	 *            attempts to import another, or {@code null} if either no
	 *            script is currently being executed or the script being
	 *            executed is not associated with a script location (e.g. a
	 *            simple script string)
	 * @param locationValue
	 *            the simple location to be resolved to a proper script location
	 * @return the resolved script location or {@code null} if it could not be resolved
	 *
	 */
	ScriptLocation resolveLocation(ScriptLocation referenceLocation,
			String locationValue);
}
    <bean id="javaScriptProcessor" class="org.alfresco.repo.jscript.RhinoScriptProcessor" init-method="register">
        <!-- ... -->
        <property name="scriptLocators">
            <map>
                <entry key="classpath">
                    <ref bean="javaScriptProcessor.classpathScriptLocator"/>
                </entry>
                <entry key="xpath">
                    <ref bean="javaScriptProcessor.xPathScriptLocator"/>
                </entry>
                <entry key="legacy">
                    <ref bean="javaScriptProcessor.legacyScriptLocator"/>
                </entry>
            </map>
        </property>
    </bean>
 
    <bean id="javaScriptProcessor.classpathScriptLocator" class="org.alfresco.repo.jscript.ClasspathScriptLocator" />
 
    <bean id="javaScriptProcessor.xPathScriptLocator" class="org.alfresco.repo.jscript.XPathScriptLocator">
        <property name="serviceRegistry" ref="ServiceRegistry"/>
    </bean>
 
    <bean id="javaScriptProcessor.legacyScriptLocator" class="org.alfresco.repo.jscript.LegacyScriptLocator">
        &lt;property name="services" ref="ServiceRegistry"/>
        &lt;property name="storeUrl">
            <value>${spaces.store}</value>
 
        <property name="storePath">
            <value>${spaces.company_home.childname}</value>
        </property>
    </bean>

Soweit zur Umsetzung auf Seiten des Repository. Den gleichen Ansatz wollte ich für Share bzw. Spring Surf äquivalent umsetzen – allerdings bin ich schnell über die Tatsache gestolpert, dass Spring Surf / Web Scripts grundsätzlich schon über einen Ansatz zum Auflösen von Abhängigkeiten verfügen. Dieser kommt im aktuellen Präprozessorschritt der Skript-Aggregation auch schon zum Tragen. Mit Hilfe eines sog. “Store” lassen sich schon längst abstrakte Pfade entweder auf dem Classpath oder einem Remote-Store, wie z.B. einem Alfresco Repository, auflösen. Dieser Mechanismus ist ausreichend erweiterbar, sodass hier ein neuer Ansatz fehl am Platz wäre.

Für Share / Spring Surf habe ich daher eine abgespeckte API in JavaScript zur Verfügung gestellt, welche auf den bestehenden Mechanismus zurückgreift – der “legacy” Modus aus dem Repository wird hiermit implizit vorgegeben.

importScript("classpath:/alfresco/templates/org/alfresco/import/alfresco-util.js", true);

Die Funktion steht sowohl für Web Scrpts als auch Template Controller zur Verfügung, und unterstützt neben explizitem Classpath wie im obigen Beispiel auch besagte abstrakte Pfade und relative Auflösung. Eine relative Auflösung wird dabei nur unterstützt, wenn das aktuell ausgeführte Skript vom Classpath geladen wurde. In einem solchen Fall wird zuerst eine relative Auflösung versucht, und erst im Anschluss – im Falle eines Fehlschlags – der angegebene Dateipfad versucht als abstrakter Pfad über einen Store zu einem Skript aufzulösen (relative Pfadangaben sind nicht eindeutig von abstrakten zu differenzieren).

Um die neue API zu testen habe ich in meiner lokalen Alfresco 4.0 Enterprise Installation üer Suchen & Ersetzen ALLE Vorkommnisse des alten import-Tags mit der neuen Funktion ersetzt. Die Umstellung verlief dabei reibungslos. In der Rhino Debugger UI tauchen alle Teilskripte fortan als einzelne Skripte auf und Breakpoints lassen sich nun auch vor Ausführung / Zusammenfügen eines Skripts verlässlich setzen. Zeilennummern in JavaScript Exceptions sind endlich überwiegend korrekt.

Debugging Alfresco #1 – Eclipse JavaScript Debugger und Alfresco Repository

Veröffentlicht von am Februar 4, 2012 6 Kommentare

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.

Eigene Klassifikationen verwalten und nutzen

Veröffentlicht von am Dezember 10, 2011 2 Kommentare

Mit Klassifikationen ermöglicht Alfresco die Auszeichnung und Einordnung von Inhalten in hierarchische Bäume von Kategorien. Das Standardprodukt liefert hier out-of-the-box einen generischen Baum mit Einordnungen bzgl. Sprache, Region und Klassifizierung von Software Dokumentationen. Mit Lucene können auf Basis dieser Bäume Abfragen formuliert werden, die Inhalte entsprechend der Zuordnung zu bestimmten Ebenen oder gar Teilbäumen auffinden können, z.B. alle Dokumente in der englischen Sprache, unabhängig vom konkreten Dialekt, d.h. zusammenfassend US-, Britisch- oder sonstiges Englisch.

Das Alfresco Wiki liefert auf der entsprechenden Seite eine sehr gute Dokumentation bezüglich Klassifikationen und Kategorien. Leider entspricht die Dokumentation aber nicht unbedingt der Masse an Projekten, die Klassifikationen einsetzen. Statt wie im Wiki beschrieben eine eigene Klassifikation anzulegen, habe ich schon viele Beispiele gesehen, bei denen lediglich der Standardbaum erweitert wurde. Aufgrund der vorhandenen Funktionalität bzgl. des Standardbaums und der damit verbundenen Einsparung von Entwicklungsaufwand ist dies grundsätzlich nachvollziehbar. Allerdings verlieren Kategorien dadurch ihre eigentlich angedachte, semantisch unterschiedliche Bedeutung, da für das gleiche Metadatum (cm:categories) beliebige Werte genutzt werden können statt aus sauber getrennten Wertebereichen mit ggf. einigen, fachlich motivierten Querverbindungen zu wählen.

Meine Kollegen und ich haben schon mehrfach Projekte realisiert, die eigene Klassifikationen nutzen, um Objekte eindeutig einzuordnen und in einzelnen Fällen sogar die Basis virtueller Navigationsstrukturen zu bilden. Neben der technischen Architektur für Klassifikationen liefert Alfresco leider nur wenig Unterstützung für die Arbeit mit eigenen Klassifikationen. Der Kategoriemanager des Web Clients kann nur mit dem Standardbaum arbeiten und selbst das in Alfresco 4.0 enthaltene Share-Äquivalent von Jan Pfitzner ist auf diesen eingeschränkt.  Damit wir – und die Entwickler der Community – nicht immer wieder das Rad neu erfinden müssen, habe ich mich zuletzt mit einer Erweiterung von Jans Komponente beschäftigt und diese als Contribution bei Alfresco eingestellt.

Grob betrachtet habe ich vier Aspekte auf Basis von Alfresco 4.0c angepasst:

  • Möglichkeit, mehrere Klassifikationen verwalten zu können
  • Möglichkeit, spezielle Subtypen von Kategorien über Forms erstellen / modifizieren zu können
  • Patch der Forms API um neue Objekte unter einer anderen Kindassoziation als cm:contains anlegen zu können
  • Patch der Object-Finder Form-Komponente um spezielle Subtypen von Kategorien nutzen zu können

Kategoriemanager - Mehrere Klassifikationen

Der Share Kategoriemanager hat – genau wie sein Vorgänger im Web Client – lediglich den Standardbaum von cm:generalclassifiable zur Administration angeboten. Um die Nutzung von eigenen Klassifikationen einfacher zu gestalten, müssen auch diese ohne zusätzlichen Entwicklungsbedarf verwaltet werden können. Mit minimalen Änderungen in der Logik des Baumaufbaus und einem zusätzlichen Daten Webscript auf Seite des Repository können nun beliebige Klassifikationen verwaltet werden. Zur Ausblendung von technischen Klassifikationen, die andersweitig genutzt und verwaltet werden, habe ich eine Konfiguration eingeführt, mit der bestimmte Klassifikationen ignoriert werden können (z.B. cm:taggable und cm:classification).

Kategoriemanager - Form-basierte Verwaltung

Kategorien sind wie nahezu alles in Alfresco ganz normale Knoten vom Typ cm:category. Für viele Einsatzzwecke mag dieser Typ ausreichen, aber gelegentlich gibt es die Notwendigkeit, fachliche Metadaten mit Kategorien zu verknüpfen. Alfresco ermöglicht sowohl die Modellierung von Subtypen von cm:category als auch die Verwendung von Aspekten an Kategorien, um diese zusätzlichen Daten verwalten zu können. Der Share Kategoriemanager jedoch unterstützte bisher nur einfache Kategorien mit einem Namen als einzige Eigenschaft. Hier habe ich auf Forms zurückgegriffen, um die notwendige Flexibilität in der Kategoretypisierung zu erreichen. Neue Kategorien werden immer per Form angelegt, während bestehende auf Basis einer ebenfalls neu eingeführten Konfiguration wahlweise durch den Insitu-Editor oder Forms modifiziert werden können. Ersterer ist der Standard für einfache Kategorien von cm:category.

Für die Form-basierte Verwaltung von Klassifikationen war es notwendig, die Forms API zu erweitern. Zum Einen bedarf es eines FormFilters, der neue Wurzelkategorien an der korrekten Position anlegt, da heirfür nur die virtuelle Referenz alfresco://category/root bekannt ist und im Standard vom TypeFormProcessor nicht aufgelöst werden kann. Zum Andern war es notwendig, Unterkategorien unter cm:subcategories in der übergeordneten Kategorie einordnen zu können – die entsprechende Möglichkeit, von cm:contains abweichende Assoziationen angeben zu können war und ist seit (mindestens) Alfresco 3.2 mit einem entsprechenden TODO im Code vorgesehen aber bisher nicht implementiert worden.

Werte aus einer eigenen Klassifikation zuordnen

Die Verwendung einer eigenen Klassifikation beim Bearbeiten von Metadaten funktionierte bisher nur dann erfolgreich, wenn cm:category für alle Kategorien genutzt wurde. Andernfalls ist es nicht möglich, tiefer als auf die erste Ebene des Klassifikationsbaums zu navigieren. Die Unterstützung von speziellen Subtypen erforderte die Anpassungen des Object-Finders, welcher den Pickerdialog für die Forms bereitstellt, und des entsprechenden Daten Webscripts im Repository. Harte Typprüfungen wurden hier gegen saubere Typhierarchieprüfungen ausgetauscht. Mit einer kleinen Spring Surf Extension kann man dann zusätzlich noch die notwendige Verknüpfung von Kategorietyp mit einem eigenen oder dem allg. Icon herstellen.

cm:name – Die erzwungene Eigenschaft

Veröffentlicht von am November 2, 2011 Keine Kommentare

Im letzten Post habe ich ein Performanceproblem beschrieben, welches auf die Nutzung von cm:name (bzw. cm:cmobject als Vatertyp) bei der Modellierung / Instanziierung von 500.000+ Datensätzen im Standard ContentStore zurückgeführt werden konnte. Entsprechend eines der aufgeführten Ansätze wollte ich diese Tage eine kleine Migration umsetzen, bei welcher die redundante Eigenschaft cm:name durch Wechsel auf den Vatertyp sys:base und anschließender Löschung der persistenten Werte von den 500.000+ Datensätzen eliminiert werden sollte. Dabei wurde mir bewusst, dass cm:name unabhängig von der Definition meiner Inhaltstypen im Data Dictionary durch das System immer gespeichert und indiziert wird – lediglich die Prüfung auf Pflicht und Constraint basiert auf der tatsächlichen Typdefinition.

Damit wird natürlich der Ansatz zur Bekämpfung des Performanceproblems wertlos – wenn es unmöglich ist, ein Node ohne cm:name in Datenbank und Index anzulegen, dann lassen sich Seiteneffekte auf die Standardnavigation von Share durch große Datensätze nicht vermeiden.

Wie äußert sich dieses Verhalten?

  • Wird ein Node ohne cm:name angelegt, so wird kein Wert gespeichert, aber beim Auslesen die UUID der NodeRef als vorgetäuschte cm:name zurück gegeben (z.B. DBNodeServiceImpl.getProperty(NodeRef, QName) oder ReferenceablePropertiesEntity.addReferenceableProperties(Node, Map<QName,Serializable>)).
  • Nur die lt. Typ definierten Eigenschaften werden bei der Anlage / einer Aktualisierung validiert. Da cm:name nur für cm:cmobject und davon abgeleitete Typen definiert ist, wird der Constraint nur für diese Typen geprüft. Die Prüfung auf Pflicht ist zwecklos, da Alfresco die Eigenschaft transparent auf die UUID setzt, wenn sie nicht explizit angegeben wurde.
  • Beim Indizieren gilt nichtmehr die Typdefinition, sondern die vorhandenen Eigenschaften und deren Definition. D.h. für Knoten, die nicht von cm:cmobject ableiten wird cm:name trotzdem indiziert, weil es a) automatisch den Wert der UUID hat, wenn es nicht gesetzt wurde und b) eine Definition der Eigenschaft gibt, welche die Indizierung vorgibt (nämlich an cm:cmobject).

Lt. SVN ist dieses Verhalten soweit von mir geprüft seit 3.2 so anzufinden und auch in der aktuellen 4.0 unverändert. Für welche Funktionalität muss diese Eigenschaft erzwungen werden, auch wenn ich sie nicht in meinem Datenmodell (bzw. den definierenden Typ) verwendet habe? Bei der in solchen Fällen üblichen Frage “Bug oder Feature” stimme ich aktuell für “Bug”. Als Partner im Auftrag eines Enterprise Kunden habe ich diesen Punkt entsprechend dem Alfresco Support übermittelt. Wenn das Verhalten bewusst so sein soll, dann wäre es zumindest sauberer, cm:name – ähnlich wie die Eigenschaften von sys:referencable – an sys:base zu hängen.

cm:name – Grenzen der Sortierbarkeit

Veröffentlicht von am November 2, 2011 Keine Kommentare

Auf Basis von Alfresco Share 3.2.2 haben wir für einen Kunden ein Compliance Management System entwickelt, welches zusätzlich zu Vertrags- bzw. Dokumentvorlagen, organisatorischen Strukturen und komplexen Workflows zur Einhaltung der Prüfungs-, Freigabe- und Dokumentationsprozesse auch die Verwaltung von ca. 500.000+ Stammdatensätze umfasst. Letztere sind als abstrakter Inhaltstyp mit Aspekten zur Gruppierung von Datenfeldern modelliert und werden regelmäßig durch einen Import mit einem externen System abgeglichen. Die Datensätze liegen allesamt im regulären ContentStore “workspace://SpacesStore”, denn 500.000 Objekte mit ca. 20 Metadatenfeldern sind nicht aureichend, um eine nennenswerte Auswirkung auf die Performance des Gesamtsystems erwarten zu können.

Entgegen den Erwartungen wurde ein Problem auf Basis von Alfresco-Eigenheiten bei der Sortierung von Lucene-Suchen beobachtet. Da der Inhaltstyp cm:cmobject als Vatertyp nutzt, hat jedes Objekt auch die geerbte Eigenschaft cm:name, welche wir mit dem Wert des fachlich eindeutigen Datensatzschlüssels belegen. Nach der ersten Synchronisierung enthielt der Index 500.000+ zusätzliche, 100% distinkte Werte für das Feld @cm:name, was zu einem merklichen Einbruch der Performance der Share Documentlibrary Navigation führte. Für uns ergab sich für jede auf @cm:name sortierende Suche ein Grund-Overhead von 3 – 5 s, bevor überhaupt die eigentliche Suche lief. Da jede Navigation innerhalb der Share Documentlibrary eine sortierende Suche in doclist.get.js auslöst, ist die Gesamtanwendung daher untragbar beeinflusst.

Warum verhält sich Alfresco schon bei einer (scheinbar) kleinen Datenmenge so schlecht? Hierfür gibt es technisch gesehen 2 Hauptgründe:

  1. Alle Feldwerte werden bei einer sortierenden Suche aus dem Index in den Speicher geladen, um vorsortiert zu werden (bei uns ca. 800.000+ distinkte Werte bei üblicherweise < 50 zu sortierenden Ergebnissen auf einer Seite).
  2. Der Lucene interne FieldCache kann bei wiederholten Anfragen nicht optimierend wirken. Bei jeder Suche kommt aufgrund der mehrfachen Kapselung des eigentlichen IndexReader eine unterschiedliche “Kapsel”-Instanz zur Geltung – der FieldCache kann per Kontrakt nur für die exakt gleiche Instanz schon geladene Werte zurückgegeben. Es werden also immer alle Feldwerte brav neu geladen. (Wer Zeit und Muße hat, kann sich den Cache mal mit einem Java Debugger anschauen und wird feststellen, dass die benötigten Daten i.d.R. schon mehrfach vorliegen aber nicht abgegriffen werden können.)

Je nachdem wie performant die I/O des Datenträgers ist, auf welchem der Index abgelegt wird, ergibt sich ein mehr oder weniger starker Effekt. Mit meinem persönlichen Arbeitslaptop inklusive SSD hab ich für gewöhnlich mehr Leistung als der Kunde für seine produktiven Maschinen zu zahlen bereit ist, und bleibe mit 1 – 2 s Verzögerung relativ verschont – bei intensiver Navigation fällt Anwendern aber auch das schnell negativ auf.

Welche Lösungen / Ansätze gibt es für die Performanceprobleme bei sortierenden Suchen?

  • Große Mengen an Stammdatensätzen sollten in andere ContentStores ausgelagert werden (separater Index). Dies geht jedoch nur, wenn keine oder nur einfach abbildbare Hierarchien mit sonstigen Inhaltsstrukturen bestehen (sollen).
  • Wenn möglich sollten Merkmale zur Sortierung über eigene, fachliche Metadaten abgebildet werden. Sobald standardisierte Eigenschaften verwendet werden, ist die Gefahr groß, durch größere Datensätze Seiteneffekte bzgl. der Sortierperformance anderer Datenbestände zu verursachen.
  • Bei Suchen über kleinere Teilmengen kann im Extremfall die Sortierung (inkl. Paging) auf JavaScript- oder Java-Seite schneller sein als mittels Lucene. (Dies wäre z.B. bei uns im Fall der Documentlibrary Navigation so, da i.d.R. nur 5 – 15 Elemente in einer Ebene liegen.)
  • Migration auf Alfresco 4.0 mit SOLR / Canned Queries

Für mich war das eine eher überraschende Erkenntnis, bedeutet es doch, dass in Alfresco bzw. Share nur wenige 100.000e Dokumente verwaltet werden können, bevor die Kernkomponente Documentlibrary langsamer reagiert. Das passte nun gar nicht zu meiner bisherigen Erfahrung, die u.a. die Verwaltung von mehreren Millionen von Objekten in einer einzigen Alfresco Instanz umfasst …

Die Probleme die Sortierung betreffend sind Alfresco schon längere Zeit bekannt. Zusammen mit ähnlichen Problemen bei PATH-basierten Suchen und Berechtigungsprüfungen bei großen Ergebnismengen wurde diese als Anlass / Bestärkung genommen, mit Alfresco 4.0 den Wechsel auf SOLR zu vollziehen sowie zentrale Abfragen auf die Datenbank zu verlegen. Gerade die Canned Queries garantieren bei Alfresco 4.0, dass bei einer sortierenden Abfrage nur die Eigenschaften der tatsächlich in der abgefragten Ebene befindlichen Objekte berücksichtigt werden.