Utilisation de l’outil VLT how-to-use-the-vlt-tool

L’outil Jackrabbit FileVault (VLT) est un outil développé par The Apache Foundation qui mappe le contenu d’une instance Jackrabbit/AEM à un système de fichiers. L’outil VLT dispose de fonctions similaires à celles d’un client du système de contrôle de code source (tel qu’un client Subversion [SVN]), offrant des opérations normales d’archivage, d’extraction et de gestion, ainsi que des options de configuration pour une représentation flexible du contenu du projet.

L’outil VLT s’exécute à partir de la ligne de commande. Ce document explique comment utiliser l’outil, notamment comment le démarrer et obtenir de l’aide. Il décrit également toutes les commandes et options disponibles.

Concepts et architecture concepts-and-architecture

Consultez la page Présentation de Filevault et Vault FS de la Documentation Apache Jackrabbit Filevault officielle pour une présentation approfondie des concepts et de la structure de l’outil Filevault.

Prise en main de VLT getting-started-with-vlt

Pour commencer à utiliser VLT, procédez comme suit :

Installation de l’outil VLT installing-the-vlt-tool

Pour utiliser l’outil VLT, vous devez d’abord l’installer. Il n’est pas installé par défaut car il s’agit d’un outil supplémentaire. En outre, vous devez définir la variable d’environnement de votre système.

Après l’avoir installé, vous devez mettre à jour les fichiers Subversion globaux ignorés. Modifiez vos paramètres svn et ajoutez les éléments suivants :

[miscellany]
### Set global-ignores to a set of whitespace-delimited globs
### which Subversion will ignore in its 'status' output, and
### while importing or adding files and directories.
global-ignores = .vlt

Configurer le caractère de fin de ligne configuring-the-end-of-line-character

VLT gère automatiquement la fin de ligne (EOL) selon les règles suivantes :

Pour garantir la comptabilité entre la configuration de VLT et de SVN, vous devez configurer la propriété svn:eol-style sur native pour l’extension des fichiers stockés dans le référentiel. Modifiez vos paramètres svn et ajoutez les éléments suivants :

[auto-props]
*.css = svn:eol-style=native
*.cnd = svn:eol-style=native
*.java = svn:eol-style=native
*.js = svn:eol-style=native
*.json = svn:eol-style=native
*.xjson = svn:eol-style=native
*.jsp = svn:eol-style=native
*.txt = svn:eol-style=native
*.html = svn:eol-style=native
*.xml = svn:eol-style=native
*.properties = svn:eol-style=native

Extraction du référentiel checking-out-the-repository

Extrayez le référentiel à l’aide du système de gestion des versions du code source. Dans svn, par exemple, saisissez ce qui suit (en remplaçant l’URI et le chemin par votre référentiel) :

svn co https://svn.server.com/repos/myproject

Synchronisation avec le référentiel synchronizing-with-the-repository

Vous devez synchroniser filevault avec le référentiel. Pour ce faire :

Vérification de la synchronisation testing-whether-the-synchronization-worked

Après avoir extrait le référentiel et l’avoir synchronisé, vous devez vous assurer que tout fonctionne correctement. Un moyen simple de le faire consiste à modifier un fichier .jsp pour voir si les changements sont répercutés une fois validés.

Pour tester la synchronisation :

Obtenir de l’aide avec l’outil VLT getting-help-with-the-vlt-tool

Après avoir installé l’outil VLT, vous pouvez accéder à son fichier d’aide à partir de la ligne de commande :

vlt --help
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Jackrabbit FileVault [version 3.1.16] Copyright 2013 by Apache Software Foundation. See LICENSE.txt for more information.
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Usage:
  vlt [options] <command> [arg1 [arg2 [arg3] ..]]
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------

Global options:
  -Xjcrlog <arg>           Extended JcrLog options (omit argument for help)
  -Xdavex <arg>            Extended JCR remoting options (omit argument for help)
  --credentials <arg>      The default credentials to use
  --update-credentials     if present the credentials-to-host list is updated in the ~/.vault/auth.xml
  --config <arg>           The JcrFs config to use
  -v (--verbose)           verbose output
  -q (--quiet)             print as little as possible
  --version                print the version information and exit
  --log-level <level>      the log4j log level
  -h (--help) <command>    print this help
Commands:
  export                   Export the Vault filesystem
  import                   Import a Vault filesystem
  checkout (co)            Checkout a Vault file system
  status (st)              Print the status of working copy files and directories.
  update (up)              Bring changes from the repository into the working copy.
  info                     Displays information about a local file.
  commit (ci)              Send changes from your working copy to the repository.
  revert (rev)             Restore pristine working copy file (undo most local edits).
  resolved (res)           Remove 'conflicted' state on working copy files or directories.
  propget (pg)             Print the value of a property on files or directories.
  proplist (pl)            Print the properties on files or directories.
  propset (ps)             Set the value of a property on files or directories.
  add                      Put files and directories under version control.
  delete (del,rm)          Remove files and directories from version control.
  diff (di)                Display the differences between two paths.
  rcp                      Remote copy of repository content.
  sync                     Control vault sync service
  console                  Run an interactive console
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------

Pour obtenir de l’aide sur une commande particulière, saisissez la commande d’aide suivie du nom de la commande. Par exemple :

vlt --help export
Usage:
 export -v|-t <arg>|-p <uri> <jcr-path> <local-path>

Description:
  Export the Vault filesystem mounted at <uri> to the local filesystem at <local-path>. An optional <jcr-path> can be specified to export just a sub tree.
  Example:
    vlt export http://localhost:4502/crx /apps/geometrixx myproject

Options:
  -v (--verbose)          verbose output
  -t (--type) <arg>       specifies the export type. either 'platform' or 'jar'.
  -p (--prune-missing)    specifies if missing local files should be deleted.
  <uri>                   mountpoint uri
  <jcr-path>              the jcr path
  <local-path>            the local path

Tâches courantes exécutées dans VLT common-tasks-performed-in-vlt

Voici quelques tâches courantes effectuées dans VLT. Pour des informations détaillées sur chaque commande, reportez-vous à la description individuelle des commandes.

Extraction d’une sous-arborescence checking-out-a-subtree

Si vous voulez uniquement extraire une sous-arborescence du référentiel, par exemple, /apps/geometrixx, vous pouvez le faire en tapant ce qui suit :

vlt co http://localhost:4502/crx/-/jcr:root/apps/geometrixx geo

Ceci crée une nouvelle racine d’exportation geo avec un répertoire META-INF et jcr_root et place tous les fichiers /apps/geometrixx dans geo/jcr_root.

Réalisation d’une extraction filtrée performing-a-filtered-checkout

Si vous avez configuré un filtre d’espace de travail et que vous voulez l’utiliser pour l’extraction, il faut soit d’abord créer le répertoire META-INF/vault et y placer le filtre, soit le spécifier sur la ligne de commande comme suit :

$ vlt co --filter filter.xml http://localhost:4502/crx/-/jcr:root geo

Un exemple de filtre :

<?xml version="1.0" encoding="UTF-8"?>
<workspaceFilter version="1.0">
    <filter root="/etc/designs/geometrixx" />
    <filter root="/apps/geometrixx"/>
</workspaceFilter>

Utilisation de l’import/export au lieu du contrôle .vlt using-import-export-instead-of-vlt-control

Vous pouvez importer et exporter du contenu entre un référentiel JCR et le système de fichiers local sans utiliser de fichiers de contrôle.

Pour importer et exporter du contenu sans utiliser le contrôle .vlt :

Utilisation de VLT using-vlt

Pour exécuter des commandes dans VLT, saisissez ce qui suit sur la ligne de commande :

vlt [options] <command> [arg1 [arg2 [arg3] ..]]

Les options et commandes sont décrites en détail dans les sections suivantes.

Options globales VLT vlt-global-options

Voici une liste des options VLT disponibles pour toutes les commandes. Reportez-vous à la description individuelle de chaque commande pour plus d’informations sur les autres options disponibles.

Commandes VLT vlt-commands

Le tableau suivant décrit toutes les commandes VLT disponibles. Reportez-vous à la description individuelle de chaque commande pour plus d’informations sur la syntaxe, les options disponibles et des exemples.

Exportation export

Exporte le système de fichiers Vault monté sur <uri> vers le système de fichiers local sur <local-path>. Vous pouvez spécifier un <jcr-path> facultatif afin d’exporter une sous-arborescence uniquement.

Syntaxe syntax

export -v|-t <arg>|-p <uri> <jcr-path> <local-path>

Options options

Exemples examples

vlt export http://localhost:4502/crx /apps/geometrixx myproject

Import import

Importe le système de fichiers local (en commençant par <local-path> dans le système de fichiers Vault sur <uri>. Vous pouvez définir un <jcr-path> en tant que racine d’importation. Si --sync est défini, les fichiers importés sont automatiquement soumis à un contrôle Vault.

Syntaxe syntax-1

import -v|-s <uri> <local-path> <jcr-path>

Options options-1

Exemples examples-1

vlt import http://localhost:4502/crx . /

Checkout (co) checkout-co

Effectue une extraction initiale à partir d’un référentiel JCR en commençant par <uri> dans le système de fichiers local sur <local-path>. Vous pouvez également ajouter un argument <jcrPath> pour extraire un sous-répertoire de l’arborescence distante. Les filtres de l’espace de travail peuvent être spécifiés et copiés dans le répertoire META-INF.

Syntaxe syntax-2

checkout --force|-v|-q|-f <file> <uri> <jcrPath> <localPath>

Options options-2

Exemples examples-2

Utilisation de JCR Remoting :

vlt --credentials admin:admin co http://localhost:8080/crx/server/crx.default/jcr_root/

Avec l’espace de travail par défaut :

vlt --credentials admin:admin co http://localhost:8080/crx/server/-/jcr_root/

Si l’URI est incomplet, il est développé :

vlt --credentials admin:admin co http://localhost:8080/crx

Analyse analyze

Analyse les packages.

Syntaxe syntax-3

analyze -l <format>|-v|-q <localPaths1> [<localPaths2> ...]

Options options-3

Statut status

Imprime le statut des fichiers et des répertoires de travail.

Si --show-update est spécifié, chaque fichier est vérifié par rapport à la version distante. La deuxième lettre spécifie ensuite l’action qui sera effectuée par une opération de mise à jour.

Syntaxe syntax-4

status -v|-q|-u|-N <file1> [<file2> ...]

Options options-4

Mettre à jour update

Copie les modifications du référentiel dans la copie de travail.

Syntaxe syntax-5

update -v|-q|--force|-N <file1> [<file2> ...]

Options options-5

Infos info

Affiche des informations relatives à un fichier local.

Syntaxe syntax-6

info -v|-q|-R <file1> [<file2> ...]

Options options-6

Commit commit

Valide et envoie les modifications de votre copie de travail au référentiel.

Syntaxe syntax-7

commit -v|-q|--force|-N <file1> [<file2> ...]

Options options-7

Rétablir revert

Rétablit le fichier de la copie de travail à son état d’origine et annule la plupart des modifications locales.

Syntaxe syntax-8

revert -q|-R <file1> [<file2> ...]

Options options-8

Résolu resolved

Annule le statut conflictuel des fichiers ou répertoires de travail.

Syntaxe syntax-9

resolved -q|-R|--force <file1> [<file2> ...]

Options options-9

Propget propget

Imprime la valeur d’une propriété dans des fichiers ou répertoires.

Syntaxe syntax-10

propget -q|-R <propname> <file1> [<file2> ...]

Options options-10

Proplist proplist

Imprime les propriétés dans des fichiers ou répertoires.

Syntaxe syntax-11

proplist -q|-R <file1> [<file2> ...]

Options options-11

Propset propset

Définit la valeur d’une propriété sur des fichiers ou répertoires.

Syntaxe syntax-12

propset -q|-R <propname> <propval> <file1> [<file2> ...]

Options options-12

Ajouter add

Ajoute des fichiers et répertoires à la gestion de versions et programme leur ajout au référentiel. Ils seront ajoutés à la prochaine validation (commit).

Syntaxe syntax-13

add -v|-q|-N|--force <file1> [<file2> ...]

Options options-13

Supprimer delete

Supprime les fichiers et les répertoires du contrôle de version.

Syntaxe syntax-14

delete -v|-q|--force <file1> [<file2> ...]

Options options-14

Diff diff

Affiche les différences entre deux chemins.

Syntaxe syntax-15

diff -N <file1> [<file2> ...]

Options options-15

Console console

Exécute une console interactive.

Syntaxe syntax-16

console -F <file>

Options options-16

Rcp rcp

Copie une arborescence de nœuds entre deux référentiels distants. <src> pointe vers le nœud source et <dst> indique le chemin de destination où le nœud parent doit être présent. Rcp traite les nœuds en diffusant les données en continu.

Syntaxe syntax-17

rcp -q|-r|-b <size>|-t <seconds>|-u|-n|-e <arg1> [<arg2> ...] <src> <dst>

Options options-17

Exemples examples-3

vlt rcp http://localhost:4502/crx/-/jcr:root/content  https://admin:admin@localhost:4503/crx/-/jcr:root/content_copy

Sync sync

Permet de contrôler le service de synchronisation Vault. Sans aucun argument, cette commande tente de soumettre le répertoire de travail en cours au contrôle de synchronisation. Si elle est exécutée dans une extraction VLT, elle utilise le filtre et l’hôte respectifs pour configurer la synchronisation. Si elle est exécutée en dehors d’une extraction VLT, elle n’enregistre le dossier actif pour la synchronisation que si le répertoire est vide.

Syntaxe syntax-18

sync -v|--force|-u <uri> <command> <localPath>

Options options-18

Codes d’état status-codes

Les codes d’état utilisés par VLT sont les suivants :

Configuration de la synchronisation FileVault setting-up-filevault-sync

Le service de synchronisation Vault sert à synchroniser le contenu du référentiel avec une représentation locale du système de fichiers et vice versa. Pour cela, il faut installer un service OSGi qui écoutera les modifications du référentiel et analysera le contenu du système de fichiers périodiquement. Il utilise le même format de sérialisation que Vault pour mapper le contenu du référentiel avec le disque.

Installation du service à l’aide de VLT installing-the-service-using-vlt

La commande vlt sync install peut être utilisée pour installer automatiquement le lot de services de synchronisation Vault et sa configuration.

Le lot est installé sous /libs/crx/vault/install et le nœud de configuration est créé sous /libs/crx/vault/com.day.jcr.sync.impl.VaultSyncServiceImpl. Au départ, le service est activé, mais aucune racine de synchronisation n’est configurée.

L’exemple suivant installe le service de synchronisation sur l’instance CRX accessible par l’URI donné.

$ vlt --credentials admin:admin sync --uri http://localhost:4502/crx install

Affichage de l’état du service displaying-the-service-status

La commande status permet d’afficher des informations relatives au service de synchronisation actif. ``

$ vlt sync status --uri http://localhost:4502/crx
Connecting via JCR remoting to http://localhost:4502/crx/server
Listing sync status for http://localhost:4502/crx/server/-/jcr:root
- Sync service is enabled.
- No sync directories configured.

Ajout d’un dossier de synchronisation adding-a-sync-folder

La commande register permet d’ajouter un dossier à synchroniser à la configuration.

$ vlt sync register
Connecting via JCR remoting to http://localhost:4502/crx/server
Added new sync directory: /tmp/workspace/vltsync/jcr_root

Suppression d’un dossier de synchronisation removing-a-sync-folder

La commande unregister permet de supprimer un dossier à synchroniser de la configuration.

$  vlt sync unregister
Connecting via JCR remoting to http://localhost:4502/crx/server
Removed sync directory: /tmp/workspace/vltsync/jcr_root

Configuration de la synchronisation configuring-synchronization

Configuration du service service-configuration

Une fois le service en cours d’exécution, il peut être configuré avec les paramètres suivants :

Configuration du dossier de synchronisation sync-folder-configuration

Chaque dossier de synchronisation stocke la configuration et le statut dans trois fichiers :

Le fichier .vlt-sync-config.properties permet de configurer les propriétés suivantes :

désactivé Active ou désactive la synchronisation. Par défaut, ce paramètre est défini sur false pour permettre la synchronisation.

sync-once Si le paramètre n’est pas vide, l’analyse suivante synchronise le dossier dans le sens spécifié, puis le paramètre est effacé. Deux valeurs sont possibles :

sync-log Définit le nom du fichier journal. Par défaut, la valeur est .vlt-sync.log.

Utilisation de la synchronisation VLT pour le développement using-vlt-sync-for-development

Pour configurer un environnement de développement selon un dossier de synchronisation, procédez comme suit :

Votre dossier local est désormais synchronisé avec le référentiel. La synchronisation est bidirectionnelle, de sorte que toute modification du référentiel est appliquée au dossier de synchronisation local, et vice versa.