Index: topia2/doc/Devel.rst
diff -u /dev/null topia2/doc/Devel.rst:1.1
--- /dev/null	Mon Apr  2 10:49:57 2007
+++ topia2/doc/Devel.rst	Mon Apr  2 10:49:52 2007
@@ -0,0 +1,191 @@
+TopiaContextFactory
+===================
+
+Le topia context est créé en fesant la demande sur le *TopiaContextFactory*.
+On peut passer en paramètre au *TopiaContextFactory* un object *Property* qui
+permet de configurer le context. Si on ne donne pas de fichier un fichier de
+propriété **TopiaContextImpl.properties** est recherché dans le classpath.
+
+Fichier de configuration
+========================
+
+Le fichier de configuration est un fichier lisible par un objet *Property*.
+Il contient différente information:
+- liste des entités à gérer
+- type de DAO à utiliser
+- option de connexion à la base de données
+- les services à activer
+
+Liste des entités à gérer
+-------------------------
+
+Il est possible de définir les entités soit directement un indiquant un
+répertoire contenant les mappings hibernate::
+
+  topia.persistence.directories=<path>
+
+doit en indiquant une liste de classe séparé par des virgule::
+
+  topia.persistence.classes=<list de classe>
+
+Le mieux est d'utiliser la liste de classe qui est non spécifique à une
+persistence ou à une plateform.
+
+Type de DAO à utiliser
+----------------------
+
+Par défaut si cette option n'est pas spécifiée, les entités sont géré par
+hibernate. On peut préciser d'utiliser le même type de DAO pour toutes les
+entités en une seul fois avec::
+
+  topia.dao.default.class=<DAO class name>
+
+On peut aussi préciser un DAO spécifique pour une entité particulière::
+
+  topia.dao.<fully qualify class name>=<DAO class name>
+
+Pour simplifer un peu l'écriture, deux alias de DAO on été fait:
+
+- **hibernate** est remplacé par *org.codelutin.topia.persistence.hibernate.TopiaDAOHibernate*
+- **flatfile** est remplacé par *org.codelutin.topia.persistence.flatfile.TopiaDAOFlatFile*
+
+La plupart du temps on ne spécifie dans ces options que le DAO de base
+(hibernate, flatfile, ...) et non pas un DAO spécifique pour l'entité qui
+aurait des méthodes de recherche supplémentaire, car la méthode **getDao**
+du *TopiaContext* encapsule automatiquement ce DAO générique par un DAO
+spécifique si celui-ci est trouvé. Le DAO spécifique doit avoir exactement
+le même nom que l'entité avec DAO à la fin. Si vous souhaitez implanter ce
+genre de DAO spécifique, il devra étendre la classe *TopiaDAODelegator*.
+
+Option de connexion à la base de données
+----------------------------------------
+
+Flatfile
+~~~~~~~~
+
+La seul option à renseigner est le répertoire ou les entités doivent être
+sauvées::
+
+  topia.dao.flatfile.directory=<path>
+
+Hibernate
+~~~~~~~~~
+
+Les options pour hibernate peuvent être directement dans le fichier de
+configuration principale ou dans un fichier de configuration secondaire dans
+ce cas il faut indiquer dans le principale le chemin de ce fichier::
+
+  topia.persistence.properties.file=<filesystem or classpath path>
+
+Les options hibernates sont les optiions hibernate classique:
+
+- hibernate.connection.username
+- hibernate.connection.password
+- hibernate.dialect
+- hibernate.connection.driver_class
+- hibernate.connection.url
+
+Les services à activer
+----------------------
+
+Il est possible d'indiqué les services à activer grâce aux options::
+
+  topia.service.<service name>=<class>
+  topia.service.security=org.codelutin.topia.security.TopiaSecurityServiceImpl
+  topia.service.index=org.codelutin.topia.index.LuceneIndexer
+  topia.service.history=org.codelutin.topia.history.TopiaHistoryServiceImpl
+
+Le nom du service doit correspondre au nom de service que le service
+retourne, sinon il est désactivé.
+
+Les services disponibles actuellement sont:
+
+- Service d'indexation full text
+- Service d'historisation des modifications des entités
+- Service de sécurité
+- Service d'upgrade automatique des données hibernates
+
+TopiaContext
+============
+
+Le *TopiaContext* permet de récupérer les services, d'ouvrir des transactions
+en récupérant des nouveaux *TopiaContext* fils, de s'enregistrer en tant que
+listener pour recevoir les notifications de modification sur les entités.
+
+Sur les *TopiaContext* fils on peut récupérer des DAO qui permettent de
+créer, modifier, recherché les entités.
+
+DAO
+===
+
+Il est possible d'avoir plusieurs types de persistance en même temps pour un
+*TopiaContext*, mais pour un même type d'entité, il ne peut y avoir qu'un
+seul type de persistence en même temps.
+
+Par défaut il existe deux type de persistence:
+
+- hibernate
+- flatfile
+
+Il est possible d'ajouter d'autre type de persistence en implantant
+*TopiaDAOAbstract*.
+
+Il est possible de faire un DAO spécial pour un type d'entité, par exemple
+pour ajouter de nouvelle méthode de recherche. Pour cela il ne faut pas
+étendre *TopiaDAOHibernate* ou *TopiaDAOFlatFile* qui rendrait spécifique à
+une persistance votre DAO qui n'ajoute que de nouvelle méthode de recheche
+mais étendre *TopiaDAODelegator* qui utilise un modèle de délégation sur le
+bon type de persistance. Le bon type de persistence est automatiquement
+injecté par le *TopiaContext* lors de la récupération du DAO.
+
+Ce DAO spécifique à une entité doit avoir le même nom que l'entity mais se
+finir par DAO. Dans ce cas le *TopiaContext* le détecte automatiquement et
+l'utilise au lieu du DAO générique hibernate ou flatfile.
+
+Pour la configuration des DAO voir la section fichier de configuration. 
+
+Entité
+======
+
+Normalement **Topia** est fait pour pouvoir générer n'importe quel type de POJO
+et les rendre persistent. Mais il est plus simple d'utiliser la génération
+de code fournit avec **Topia** pour générer les entités à partir d'un
+diagramme UML. Dans ce cas toutes les entités héritent de *TopiaEntity* qui
+contient des méthodes pour s'enregistrer sur les modifications des attributs
+ou pouvoir lever un droit de veto sur une modification. Sont aussi
+disponible les méthodes:
+
+- getTopiaId
+- getTopiaVersion
+- getTopiaCreationDate
+- getTopiaContext
+- getComposite: Retourne tous les objets qui seront effacé si cet objet est effacé
+- getAggregate: Retourne les objets en lien avec celui-ci
+
+Lorsque l'on utilise la génération on peut implanter une classe qui hérite
+du *Abstract* généré et qui se finisse par Impl. Par exemple si dans notre
+modèle nous avons la classe *Toto* il sera généré une interface *Toto* et
+une classe abstraite *TotoAbstract*, il faudra alors implanter *TotoImpl*::
+
+  extends TotoAbstract extends TopiaEntityAbstract implements Toto
+  extends TopiaEntityAbstract implements *TopiaEntity
+
+Cette classe impl permet d'ajouter des méthodes métiers à l'entité ou des
+méthode d'accès différent sur les attributs.
+
+TopiaService
+============
+
+Pour implanter un TopiaService il faut absolument créer une interface qui
+hériter de l'interface *TopiaService* et mettre dans cette interface un
+attribut static qui définit le nom du service::
+
+  public static final String SERVICE_NAME = "monservice";
+
+Un service peut avoir besoin de nouvelle entités pour fonctionner pour cela
+il faut retourner la liste des entités grâce à la méthode
+**getPersistenceClasses**. 
+
+Après instanciation du service par le **TopiaContext** celui-ci est
+initialisé grâce à la méthode **init(TopiaContextImplementor)**. Il peut
+alors se mettre listener sur le context ou les DAO par exemple.