introduzione

Questo tutorial è stato creato per coloro che hanno bisogno, in qualche modo, di configurare Alfresco su un progetto. E quindi all’inizio pensi: “Cos’è questo?!” Ma alla fine imparerai:

• Come creare un progetto Alfresco da zero utilizzando Alfresco Maven SDK
• Cosa dovrebbe succedere a seconda delle impostazioni
• Come creare ed eseguire un test
• Come creare un artefatto adatto per l'incorporamento o la condivisione con la comunità

Questo tutorial dovrebbe essere considerato un punto di partenza prima di passare a un apprendimento più dettagliato su aspetti come la modellazione dei contenuti, la personalizzazione di azioni e comportamenti, flussi di lavoro aggiuntivi o script web.

Prima di iniziare, una breve digressione: ci sono quasi sempre molti percorsi alternativi per arrivare ad una soluzione. In questo tutorial ti accompagnerò nel modo più semplice e diretto, un percorso sicuro che ti aiuterà a capirlo più velocemente. Successivamente potrai modificare alcune cose o esplorare altri percorsi, se lo desideri.

Concetti basilari.

Non è necessario sapere molto su Maven, Alfresco o sul motivo per cui è necessario questo SDK prima di iniziare a utilizzarlo, ma alcune conoscenze possono essere utili in qualche modo, quindi permettimi di illustrarti rapidamente i concetti di base.

Apache Maven

Apache Maven è uno strumento di gestione delle build. Ha molte funzionalità, ma la principale è che fa risparmiare tempo nel capire su quali dipendenze (e dipendenze delle dipendenze) si basa il tuo progetto. Maven può recuperare e memorizzare nella cache queste dipendenze per te. Se hai mai passato del tempo cercando di capire quale file JAR viene dopo quale file JAR, allora l'utilità di uno strumento del genere è ovvia.

Pacchetti modulari Alfresco (AMP)

AMP è un file ZIP con una struttura di directory che segue determinate convenzioni. I file AMP vengono utilizzati per condividere e distribuire facilmente le impostazioni sulla piattaforma Alfresco. Se il tuo progetto necessita di creare impostazioni personalizzate a livello di repository (app Web/alfresco), crea un "repo" AMP. Se il tuo progetto necessita di creare impostazioni a livello di condivisione (app Web/condivisione), crea un AMP "condividi". È abbastanza tipico per un progetto che, quando sono necessarie modifiche a entrambi i livelli, si creino due AMP.

SDK Alfresco Maven

I programmatori di oggi sono abituati a framework potenti in cui una directory vuota si riempie completamente di file in un minuto e il momento successivo il tuo progetto è pronto per essere lanciato. Perché gli sviluppatori di Alfresco dovrebbero accontentarsi di meno?

L'obiettivo dell'SDK basato su Maven è creare le condizioni più semplici possibili per avviare lo sviluppo per Alfresco. L'SDK è costituito da un modello di progetto (un "archetipo" nella terminologia Maven) e da alcune funzionalità integrate che indicano a Maven come creare AMP e distribuirli su Alfresco.

Se scrivi la tua applicazione separatamente da Alfresco e Share WARs, non avrai bisogno dell'SDK di Alfresco Maven. Ma se hai intenzione di scrivere codice eseguibile in una di queste applicazioni Web, Alfresco Maven SDK è il punto di partenza.

Che dire del vecchio SDK basato su Ant?

Alfresco ha fornito questo SDK scaricabile fin dall'inizio. L'SDK conteneva un contenitore ZIP con le dipendenze necessarie per compilazione, codice sorgente, documentazione e progetti Eclipse di esempio. Questi esempi hanno utilizzato un builder basato su Ant.

Non c'era niente di sbagliato in questo approccio, ma le piattaforme di sviluppo si sono evolute e gli SDK di Ant non sono riusciti a evolversi con loro. Ad oggi, parti di questi esempi sono obsolete (le API native dei servizi Web, ad esempio, o l'interfaccia utente di Alfresco Explorer) e non ci sono abbastanza esempi per parti estremamente importanti come CMIS, script Web e flussi di lavoro avanzati che utilizzano Activiti.

Oltre ai suoi esempi obsoleti, è richiesto il vecchio Ant SDK. Gli sviluppatori stanno facendo troppo lavoro. Con Alfresco Maven SDK, non devi nemmeno scaricare nulla: devi solo creare il tuo progetto e iniziare a scrivere codice.

Ora hai un livello elevato di conoscenza di Apache Maven, AMP e Alfresco Maven SDK. È tempo di vedere tutto in azione

Il tuo primo progetto

Lascia che ti mostri quanto è facile iniziare a sviluppare per Alfresco utilizzando Alfresco Maven SDK. Prima di iniziare, devo ricordarti di aver installato JDK 1.7 e Apache Maven 3. Non è necessario scaricare nient'altro. Sul serio. Anche all'aperto.

1. Crea una directory vuota. Presto creeremo alcune directory aggiuntive.
2. Ora creiamo un progetto vuoto. Supponiamo che tu voglia creare qualcosa che distribuirai nel repository Alfresco, ad esempio un modello di contenuto personalizzato, diverse azioni di regole personalizzate, un nuovo set di script Web o alcuni processi aziendali Activiti. Non importa davvero. Per creare un nuovo progetto, esegui il comando:

   archetipo mvn:genera\
   -DarchetypeCatalog=https://artifacts.alfresco.com/nexus/content/groups/public/archetype-catalog.xml\
   -Dfilter=org.alfresco.maven.archetype:

3. Maven farà un po' di lavoro e alla fine ti chiederà di selezionare "archetipo". La tua selezione di base dalle librerie di modelli di progetto. Ce ne sono due disponibili qui. Uno si chiama "alfresco-amp-archetype" e l'altro "alfresco-allinone-archetype". Il nostro obiettivo è creare un AMP che possa essere distribuito in Alfresco, quindi il primo punto è ciò di cui abbiamo bisogno. Digitare 1 e premere Invio.
4. Maven ora ti chiede una versione specifica del modello su cui baserai il tuo progetto. Attualmente, l'ultima versione è 1.1.1, che è la quinta opzione nell'elenco, quindi premi 5 e Invio.
5. Maven chiede informazioni sull'ID gruppo. È simile al "pacchetto Java". I miei esempi si basano sempre sul fatto che lavoro presso un'azienda fittizia chiamata SomeCo, quindi inserirò qui "com.someco". Digita qualcosa che abbia senso per te e premi Invio.
6. Il prossimo è l'artifactId. Consideralo come il nome del tuo progetto. Questo diventerà anche il tuo ID AMP, quindi scegli qualcosa di speciale. Dovresti anche aggiungere la riga "-repo" al tuo artifactId perché questo modulo verrà integrato nel repository. Chiamerò il mio "someco-mvn-tutorial-repo" e premerò Invio.

7. A questo punto Maven ti mostrerà i valori che hai inserito, aggiungerà alcuni altri valori predefiniti e ti chiederà di confermare la selezione. Se vuoi cambiare qualcosa, puoi selezionare "N" e quindi apportare le modifiche o "Y" per continuare. Puoi sempre modificare questi valori in seguito, se necessario. Premere "Y" e poi Invio.

Maven ora farà del lavoro. Al termine otterrai quanto segue:

• Un progetto strutturato per supportare il tuo sviluppo Alfresco
• File di configurazione predefiniti
• Codice Java minimo per test unitari aggiuntivi per verificare che tutto funzioni
• Configurazione richiesta per eseguire l'istanza locale di Alfresco richiesta per il test
• File XML POM (Project Object Model) predefinito che indica a Maven quali dipendenze ha il tuo progetto

Eseguiamolo

Non hai ancora caricato nulla. Non hai ancora modificato nulla. Tutto quello che hai fatto è stato dire a Maven di creare un progetto basato sul modello, ma ho ottime notizie: il tuo progetto è pronto per essere eseguito proprio adesso.

Prova questo:

cd someco-mvn-tutorial-repo
mvn test di integrazione -Pamp-to-war

Se guardi l'output, vedrai che Maven scarica tutto il necessario per compilare il progetto, creare l'AMP, distribuire l'AMP su Alfresco WAR, distribuire Alfresco WAR sul server Tomcat incorporato ed eseguirlo. Alla fine vedrai qualcosa di simile a:

2014-01-15 18:01:19,339 INFO [repo.module.ModuleServiceImpl] [localhost-startStop-1] Trovato 1 modulo(i).
2014-01-15 18:01:19,480 INFO [repo.module.ModuleServiceImpl] [localhost-startStop-1] Installazione del modulo 'someco-mvn-tutorial-repo' versione 1.0.1401151758.

Ciò significa che i moduli del tuo progetto sono stati generati e riconosciuti dal server Alfresco.

Dopo aver visto:

16 gennaio 2014 8:38:20 org.apache.coyote.AbstractProtocol start INFO: Avvio di ProtocolHandler ["http-bio-8080"]

Dovresti essere in grado di aprire:

http://localhost:8080/alfresco

E accedi utilizzando "admin" e "admin".

Quando hai finito di ammirarlo, torna alla finestra in cui hai eseguito il comando Maven e premi ctrl-c per spegnere il server.

Se ricevi un errore di memoria insufficiente durante l'esecuzione di un test di integrazione, potrebbe essere necessario inserire alcuni parametri JVM per le opzioni di memoria in Maven. Una possibile soluzione è impostare la variabile di ambiente MAVEN_OPTS. Ad esempio, ho impostato i miei valori su:

-Xmx1024M -XX:DimensionePermMax=512m

Utilizza MAVEN_OPTS per impostarlo in modo tale da non visualizzare errori di overflow della memoria.

Cos'era?

Hai chiesto a Maven di eseguire "test di integrazione" per utilizzare il profilo "amp-to-war". Ciò ha portato alla realizzazione del progetto, alla sua distribuzione come AMP in un nuovo Alfresco WAR e all'esecuzione del server Tomcat incorporato. Successivamente, hai potuto accedere al vecchio client Alfresco Explorer e lavorare con il repository, testando il tuo modulo.

Se guardi nella directory di destinazione, vedrai AMP creato e successivamente distribuito in Alfresco WAR. Nel mio caso si chiama "someco-mvn-tutorial-repo.amp". Questo file è ciò che dovresti fornire al tuo team IT se sei pronto per applicare le modifiche a livello di repository al server Alfresco live.

Altri comandi di creazione

Potrebbe non essere sempre necessario avviare il server Alfresco e lasciarlo in esecuzione. Se vuoi semplicemente creare il progetto, eseguire uno unit test e creare il pacchetto AMP, puoi fare:

pacchetto mvn

Se desideri installare AMP nel tuo repository Maven locale, esegui:

installazione mvn

Potresti aver notato che il progetto include un semplice unit test per impostazione predefinita. Per impostazione predefinita, Maven eseguirà automaticamente gli unit test nel tuo progetto. Puoi vederlo nell'output della console:

-------------------------------------------------- -----
 PROVE
-------------------------------------------------- -----
Esecuzione di org.alfresco.demoamp.test.DemoComponentTest

È buona norma assicurarsi che il progetto includa sempre test unitari e li esegua ogni volta che si compila. Molte organizzazioni utilizzano strumenti CI (Continuous Integration) che dipendono da questi test. Se per qualche motivo non vuoi eseguire il test, puoi saltarlo, qualcosa del genere:

mvn install -DskipTests=true

Se vuoi rimuovere tutto il materiale compilato creato da Maven e ricominciare da capo, puoi eseguire:

sono molto pulito

Se desideri eliminare anche il database integrato, i contenuti salvati di Alfresco, gli indici e i log che vengono sempre creati durante l'esecuzione del test del server, puoi eseguire:

mvn clean -Elimina

Ora sai come creare un nuovo progetto Alfresco utilizzando un modello e hai le nozioni di base per costruirlo con o senza test. Il prossimo passo è imparare come lavorare con il tuo progetto nell'IDE.

Registrazione

Il file log4j.properties si trova nella directory dei moduli, incluso il file log4j.properties

log4j.logger.org.alfresco.demoamp.DemoComponent=${module.log.level}

Probabilmente vorrai sostituirlo con le tue impostazioni adatte alla struttura del tuo pacchetto.

Per configurare module.log.level puoi farlo quando avvii Maven, in questo modo:

mvn install -Dmodule.log.level=DEBUG

Oppure puoi modificare pom.xml e aggiungerlo alle proprietà, qualcosa del genere:

<module.log.level>DEBUG</module.log.level>

Se modifichi pom.xml, AMP riceverà queste impostazioni una volta creato e, successivamente, il WAR in cui è distribuito AMP scriverà i log. Questo potrebbe (o meno) essere ciò che desideri. Se non sei sicuro, potrebbe essere meglio impostare i valori utilizzando la riga di comando in quanto ciò ti impedirà di confondere accidentalmente i valori nel tuo AMP.

Architetto ECM