Présentation de l'API 'Resources'

Par Ioan Calapodescu (home)
 

Ce document présente l'API 'Resources' : objectifs, architecture, détails d'implémentation, exemples et tests. Vous y trouverez aussi des liens et explications pour la javadoc, les sources et les binaires.

1.0. Pour commencer ...

1.1. Objectifs

Les principaux cas d'utilisation de cette API seraient dans des plugins/modules pour Eclipse, Netbeans, etc. . Voici quelques cas d'utilisation intéressants :

• Documentation en francais à portée de la main :
  Actuellement, à ma connaissance, aucun EDI ne contient de documentation sur la techno en elle même, mais plutôt sur ses propres fonctionnalités. Et quand c'est le cas, c'est naturellement en anglais et des "cours d'intro" dont on fait vite le tour.
  Avec un de nos plugins : FAQs, codes sources et tutoriels seront directement intégrés dans l'EDI, plus besoin d'ouvrir un navigateur et de faire des "allers-retours".
• Recherche centralisée :
  Prenons l'exemple du pauvre bougre qui fait du dév. web en Java, et qui pour être à la page fait un peu d'AJAX. Les docs qui l'intéressent se retrouvent disséminés entre la demi-douzaine de FAQs Java, les FAQs CSS, XML, Javascript, les pages de codes sources et les centaines de tutos répartis sur les pages cours des rubriques correspondantes. Bref, même s'il connaît bien dvp, il en a peut-être pour des heures pour retrouver ce qu'il cherche.
  Avec un de nos plugins : il n'aura qu'à "cocher" les ressources qui l'interessent (par exemple la FAQ Java EE, la FAQ XML, la FAQ Javascript, les codes sources Java et les tutos Java) et "taper" AJAX pour obtenir les docs qu'il faut.
  Pour un exemple de recherche multi-ressources voir "Hello Resources World".
• Nouvelles en direct :
  Prenons l'exemple de la nouvelle page d'accueil de Netbeans 5.5 : elle est sympa, mais je suis prêt à parier qu'elle sera quasiment inutilisée. Pourquoi ? Pour commencer, elle ne contient que des news sur Netbeans, de plus c'est à 90% en anglais. Bref, l'interet ma parait assez limité pour des développeurs Java francophones.
  Par contre, avec cette API, on peut facilement imaginer le même type de page (pour Eclipse et Netbeans) avec des nouvelles en francais, sur l'ensemble des technos Java et plus si affinités (par exemple les news de la rubrique Dév. Web pour les utilisateurs d'Eclipse en tant qu'EDI PHP).

1.2. Statut

En dehors des tests unitaires, pour essayer l'API, j'ai écrit une petite application Eclipse RCP que je pense adapter par la suite en plugin pour l'EDI du même nom .

1.3. Ce document

2.0. Pour rentrer dans le vif du sujet ...

2.1. Getting started

2.1.1. Prérequis et téléchargements

Pour finir, vous aurez aussi besoin d'un serveur local, au hasard Tomcat.

2.1.2. Installation et tests

Eclipse

Copiez les deux projets dans votre workspace et importez les : File > Import > Existing Project in Workspace Déployez le projet ResourcesExample à l'adresse http://localhost:8080/ResourcesExample Lancez les tests unitaires. Click droit sur AllTests (projet Resources) > Run > Run as JUnit test

Netbeans

Importez ResourcesExample : File > New project > Web > Web Application with existing sources, sélectionnez ResourcesExample, Next, Finish. Exécutez le projet (F6). Si vous utilisez SAS, il n'y a pas de modifications à faire, par contre si vous utilisez le Tomcat intégré (ou autre chose) regardez le warning ci-dessous. Importez Resources : Supprimez le build.xml dans Resources File > New Project > General > Java project with existing sources, sélectionnez Resources. Nommez le projet Resources. Ajoutez les répertoires src et tests comme répertoires source et test. Finish Ajoutez les jars contenus dans lib au classpath (click droit sur Library > Add Jar/folder) Lancez les tests : click droit sur test.AllTests > Run file

Ant

Déployez ResourcesExample/ResourcesExample.war. Par exemple, pour tomcat : copiez le fichier dans TOMCAT_HOME/webapps et (re)démarrez Copiez Resources/libs/junit-3.8.1.jar dans ANT_HOME/libs Dans Resources, exécutez : ant build AllTests

Adresse de déployement

Si vous ne pouvez pas déployer ResourcesExamples à l'adresse http://localhost:8080/ResourcesExample : remplacez ses occurrences dans les fichiers : repository.xml, listeners-repository.xml et AbstractTest (projet Resources).

Sinon, ca craint, on vous a dupé, faites une réclamation :(

2.1.3. "Hello Resources World"

Fichier repository.xml

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>

<resources:resource xmlns:resources="http://www.developpez.com/resources">
	<id>repJava</id>

    <title>Répertoire de ressources Java</title>
    <!-- ... -->
    <element>
        <id>faqJavaSE</id>

        <title>FAQ Java SE</title>
        <url>http://java.developpez.com/faq/java</url>
        <authors/>
        <contentUrl>http://localhost:8080/ResourcesExample/faq-java.xml</contentUrl>

        <contentReader>com.developpez.resources.readers.FAQReader</contentReader>
    </element>
    <!-- ... -->

    <element>
        <id>sourcesJava</id>
        <title>Codes sources Java</title>
        <url>http://java.developpez.com/sources</url>

        <authors/>
        <contentUrl>http://localhost:8080/ResourcesExample/sources-java.xml</contentUrl>
        <contentReader>com.developpez.resources.readers.FAQReader</contentReader>
    </element>

	<!-- ... -->
    <element>
        <id>blogRubrique</id>
        <title>Blog de la rubrique Java</title>

        <url>http://blog.developpez.com/?blog=42</url>
        <contentUrl>http://blog.developpez.com/xmlsrv/rss2.php?blog=42</contentUrl>
        <contentReader>com.developpez.resources.readers.SyndicationReader</contentReader>

    </element>
    <!-- ... -->
</resources:resource>

Ce qu'il y a d'important de noter c'est que chacun de ces éléments a un identifiant, une URL de contenu et un lecteur de contenu. Par exemple, l'id de la FAQ Java est faqJavaSE, son url de contenu est http://localhost:8080/ResourcesExample/faq-java.xml et son lecteur de contenu est un FAQReader.

HelloResourcesWorld

2. import java.util.*; 

3. import com.developpez.resources.*; 

4. import com.developpez.resources.search.*; 

5. public class HelloResourcesWorld { 

6.     public static void main(String ... args) throws Exception { 

7.     	// Chargement du répertoire 

8.         String url = "http://localhost:8080/ResourcesExample/repository.xml"; 

9.         Resource repository = Resource.getRepository(url); 

11.         // Chargement des ressources 

12.         Resource faq = repository.getResource("faqJavaSE"); 

13.         Resource sources = repository.getResource("sourcesJava"); 

14.         Resource blog = repository.getResource("blogRubrique"); 

16.         // Recherche dans l'ensemble des ressources 

17.         String query = "xml"; 

18.         List<SearchResult> search = Search.search(query, faq, sources, blog); 

20.         // Tri et affichage du résultat de la recherche 

21.         Collections.sort(search, Search.RATE_COMPARATOR); 

22.         for(SearchResult result : search){ 

23.             System.out.println(result.getElement().getTitle()); 

24.         } 

25.     } 

26. } 

1. On a chargé le répertoire : celui-ci est en fait une ressource "comme les autres", à la différence que sont reader est fixé (DefaultReader). A partir de l'url passée en paramètre ce dernier charge une instance de Resource : notre répertoire.
2. On a chargé nos ressources : la méthode getResource(id) commence par chercher dans le répertoire un élément ayant le bon identifiant. Une fois celui-ci trouvé, un reader correspondant à contentReader est instantié et charge une instance de Resource à partir de contentUrl.
3. on a effectué notre recherche : la classe Search a parcouru l'ensemble des ressources (leurs catégories, sous-catégories, éléments, ...) et a recherché le terme query dans les titres, les descriptions , voir le contenu de tout ce beau monde.

2.2. Architecture

2.2.1. Vue d'ensemble

• com.developpez.resources : contient un ensemble d'objets définissant nos ressources, leurs catégories et leur éléments.
• com.developpez.resources.readers : contient l'interface Reader qui se résume à deux méthodes permettant simplement de récupérer une instance de Resource à patir d'un URL. Ce package contient aussi différentes implémentations de ces lecteurs : des lecteurs de FAQs, de pages sources, de pages livres, de flux RSS, etc.
• com.developpez.resources.writers : contient l'interface Writer dont vous aurez deviné l'utilité. Les implémentations actuellement présentes nous permettent deux choses : la gestion d'un cache physique de ressources et la transformation de certaines ressources (par exemple une FAQ en flux RSS, Atom, etc.).
• com.developpez.resources.search : contient une classe utilitaire permettant d'effectuer ddes recherches et une représentation de résultat de recherche (l'élément correspondant, une note, etc.).
• com.developpez.resources.listeners : contient "le" listener de l'API. A part le fait qu'il doit se sentir très seul, la seule chose qu'on peut remarquer est sa fonctionnalité qui est de nous informer de la présence de nouveaux éléments dans les ressources (par exemple quand un flux RSS ou une FAQ est mise à jour, manuellement ou automatiquement, selon les circonstances).
• com.developpez.resources.listeners : contient ResourceException. Vous connaissez SQLException ? Eh ben, c'est pareil : une bonne grosse classe pour encapsuler les problèmes que l'on peut rencontrer lors de la lecture d'une ressource (url de contenu inexistante ou innaccessible, flux xml mal formés, ...) ou de son écriture.

2.2.2. Les ressources

Cliquez pour agrandir

2.2.3. Les readers

Cliquez pour agrandir

2.2.4. Les writers

Cliquez pour agrandir

2.2.5. Les autres

Cliquez pour agrandir

3.0. Pour aller plus loin ...

3.1. Téléchargements, liens et docs

3.2. Conclusion

Pensons aux autres

Cette API est construite sur la plateforme Java, ce n'est pas pour autant qu'elle va être réservée à la rubrique Java.

En effet, des outils comme Eclipse et Netbeans ne servent pas qu'au développement Java. Ils conviennent aussi parfaitement au développements : PHP, Ruby, Python, Perl, C/C++, ...

Sans parler du fait que des rubriques comme SGBD (MySQL, Oracle, ...), Développement Web (HTML, CSS, Javascript), XML proposent des ressources utiles à de nombreux langages/plateformes de développement.

Le plugin Eclipse

Une fois qu'on aura eu l'occasion de discuter de tout ca, je pense que je vais m'attaquer à la création du plugin pour Eclipse.

Entre la "finalisation" de l'API et ce plugin, je ne pense pas avoir le temps de m'occuper, en plus, d'un module pour Netbeans. Il serait donc intéressant qu'on puisse monter plusieurs équipes pour créer tout ce dont a besoin.
Des volontaires ? :)

Pourquoi un serveur ?

C'est juste pour faire tourner le répertoire de ressources utilisé pour les tests (la description du répertoire, des faqs, des flux choisis, ...).

L'avoir en local permet juste de ne pas dépendre d'une connexion web pour le développement. Ca a aussi l'avantage de rendre les tests unitaires distribuables sans avoir à "polluer" je ne sais quel serveur avec les fichiers utilisés par les tests.

Réclamations

Contactez moi et décrivez moi le problème ;)

Contenu

Pour cette FAQ l'url de contenu est simplement le fichier xml qu'on utilise avec le kit.