Author: echatellier Date: 2013-12-05 15:44:36 +0100 (Thu, 05 Dec 2013) New Revision: 178 Url: http://forge.codelutin.com/projects/isis-fish-docs/repository/revisions/178 Log: Traduction de la page API par Sigrid Modified: trunk/src/site/en/rst/v4/index.rst trunk/src/site/en/rst/v4/user/tutorials/useAPI.rst Modified: trunk/src/site/en/rst/v4/index.rst =================================================================== --- trunk/src/site/en/rst/v4/index.rst 2013-12-05 14:31:10 UTC (rev 177) +++ trunk/src/site/en/rst/v4/index.rst 2013-12-05 14:44:36 UTC (rev 178) @@ -45,7 +45,7 @@ .. _Tutorials: user/tutorials.html .. _FAQ: user/FAQ.html .. _Developer manual: devel/index.html -.. _APIs documentation: user/API.html +.. _APIs documentation: user/useAPI.html .. _ISIS scripts examples: user/scripts.html .. _R scripts examples: user/scriptsR.html .. _Changes in version 4.0: user/changements40.html Modified: trunk/src/site/en/rst/v4/user/tutorials/useAPI.rst =================================================================== --- trunk/src/site/en/rst/v4/user/tutorials/useAPI.rst 2013-12-05 14:31:10 UTC (rev 177) +++ trunk/src/site/en/rst/v4/user/tutorials/useAPI.rst 2013-12-05 14:44:36 UTC (rev 178) @@ -5,7 +5,7 @@ .. * $Id$ .. * $HeadURL$ .. * %% -.. * Copyright (C) 1999 - 2010 Ifremer, Code Lutin +.. * Copyright (C) 1999 - 2013 Ifremer, Code Lutin, Sigrid Lehuta .. * %% .. * This program is free software: you can redistribute it and/or modify .. * it under the terms of the GNU General Public License as @@ -23,115 +23,88 @@ .. * #L% .. - -Tutorial on APIs use -==================== +Tutorial for the use of APIs +========================== -This tutorial have not been translated to english yet. +Before you start... +First, don't panic! +You need to know that all the values entered in the interface by users are stored in corresponding ISIS objects. To modify those values, that is to say, the attributes of the objects, you need to know their nature and structure, how to access and modify them. To do so, the dependency between objects must be understood. The architecture of the database is available here ( `Modele ISIS-Fish`_ ) but also reflected by the architecture of the tree in the input interface. -Avant tout il faut savoir, que toutes les valeurs saisies dans l'interface de -saisie par l'utilisateur sont stoquées dans les objets d'ISIS correspondants. -Pour modifier ces valeurs avant ou en cours de simulation, il faut connaitre -leur nature et leur structure, savoir comment y accéder et les modifier. -Pour savoir comment y accéder il faut connaitre les dépendances entre objets -(objets qui sont des attributs d'autres objets). Pour cela on consulte -l'architecture de la base de donnée ( `Modele ISIS-Fish`_ ) qui se reflète dans -l'architecture de l'interface de saisie. +To know how to pass from an object to another you need to find the corresponding method in the API. -Pour savoir comment passer d'un objet a un autre il faut connaitre les méthodes -appliquables aux objets : tout est dans l'API. +Remark: Start by getting to know the various Java objects (double, boolean, string, integer, equation, matrix,...)(cf tutoriaux JAVA). -Remarque : Il vaut mieux commencer par se familiariser avec les differents types -d'objets JAVA (double, boolean, string, integer, equation, matrix,...), les -attributs et les methodes (cf tutoriaux JAVA). +Here is an example « step by step » in the case where you want to modify the natural mortality equation (in a simulation plan for instance). We want to replace temporarily the equation in the database with another one. +You need to create an object equation. +First start by creating an object String containing the new equation:: -Voici un exemple "pas à pas" pour le cas ou l'on voudrait modifier l'equation de -mortalité naturelle dans un plan d'analyse par exemple. On veut remplacer -provisoirement la valeur de la base par une autre. On crée un objet String -rempli avec l'autre valeur par exemple:: - String mortalitenaturelle = "if (groupe.getId() == 0) return 1.5; else return 0.2;" -Se poser la question : "Dans la base de donnée où se trouve la mortalité naturelle ?" +Then ask yourself: "In the database where is natural mortality?" ------------------------------------------------------------------------------------- -Réponse : dans l'interface de saisie, elle est dans la branche "population" et -l'onglet "equations". -(au passage le titre de l'onglet nous renseigne sur le type d'objet auquel on a -affaire : ya de grandes chances pour que parmi la batterie d'objets possibles -(int, double, matrice...) la mortalité naturelle soit une equation ;-) ) +Answer: In the input interface, in the branch for "population" and the equation tab. +(here the name of the tab inform on the type of objects listed here, most likely equations). -En francais on dirait "dans population, va chercher l'objet equation de -mortalité naturelle, et attribut lui la valeur du string mortalitenaturelle", ya -pu qu'a le dire en java. +In English, you would say, in population, get the equation for natural mortality which is filled with a string. -Ouvrir la page des APIs +Open API pages ----------------------- -Dans la colonne de gauche de l'API (sous "all classes") on cherche l'entite -"population" et on clique dessus. +On the left, under « all classes », look for th entity « population » (the one in italic), clic on it. -Les méthodes disponibles +Available methods ------------------------ -Toutes méthodes que l'on peut appliquer à un objet population (colonne de -droite) s'affichent , et le type d'objet qu'elles renvoient (colonne de gauche). +All the methods available for an object of type « population » appear in a table. The second column tells the method name and arguments it takes, the first column tells the type of object the method returns. +The code you will write should look like this:: +Type_of_object_returned_by_the_method_on_left_side objectName = population.method(method arguments); + +There are mostly 2 kinds of methods : -c'est a dire que les lignes de commandes qu'on ecrira seront de la forme:: +* methods "get" : get an object +* methods "set" : set the value of an object. - objet_renvoyé_indiqué_à_gauche nomObjet = population.methode_ecrite_à_droite(argument de la methode); +In our example we eventually want to change a value, so "set". -Il y a surtout deux grands types de méthodes : - -* les méthodes "get" : qui vont chercher un objet -* les méthodes "set" : qui assignent une valeur a un objet. - -Dans notre exemple on veut changer l'equation de mortalité naturelle, c est donc -un set ! - -On cherche une méthode qui parle de mortalité naturelle... +Look for a method dealing with natural mortality ---------------------------------------------------------- -On trouve getNaturalDeathRate() qui renvoit un objet equation (c'est l'objet -equation qui contient la valeur de l'equation de mortalite naturelle remplie par -l'utilisateur) et setNaturalDeathRate(Equation naturalDeathRate) pour laquelle -on doit passer un objet equation (une equation de naturalDeathRate) en argument. +You find getNaturalDeathRate() which returns an equation (it is the object equation which contains the value of the equation of natural mortality filled by the user in the interface) and setNaturalDeathRate(Equation naturalDeathRate) which receives as argument an equation. -(en cliquant sur le nom de la méthode on a une description sommaire de ce -qu'elle fait) +(Note: a clic on the method name gives you further information on the method) -setNaturalDeathRate() parait être ce qu'on veut faire... -mais la méthode setNaturalDeathRate prend en argument une equation, on ne peut -donc pas faire:: +setNaturalDeathRate() seems appropriate... +However the method takes an equation as argument and not a String, we thus cannot write:: pop.setNaturalDeathRate(mortalitenaturelle); -puisque mortalitenaturelle n'est pas une equation mais un string. - - -Créer une équation +Create an equation ------------------ -Du coup il faut trouver autre chose qui fasse le lien entre un string et une -equation. En cliquant sur "equation" dans la page d'API on tombe sur la page des -méthodes qui s'appliquent aux objets qui sont des equations. On trouve une -méthode .setContent(String ) qui prend en argument un string. Ca veut dire que -si on a une equation, on peut lui changer sa valeur en utilisant cette methode -avec un string en argument. -L'equation dont on veut changer la valeur on sait la récupérer:: +So next step, how to transform a string into an equation. +Clic on « equation » on the API page, you are re-directed toward the pages of methods for equations. You will find a method .setContent(String ) which takes a string as argument and returns an equation. So that means that applied to an equation this method changes the value of the equation according to whats written in the string. +We know how to GET the equation we want to change:: +Equation eqMortalite = pop.getNaturalDeathRate(); - Equation eqMortalite = pop.getNaturalDeathRate(); - -L'objet eqMortalite est un objet equation:: - +Then to change its content:: eqMortalite.setContent(mortalitenaturelle); -et là on a le droit vu que mortalitenaturelle est un string et que la méthode -prend un string en argument. +Voilà ! +Note it could also be done in a single line:: +pop.getNaturalDeathRate().setContent(mortalitenaturelle); -et voilà c'est fait ! +Note too that even if the equation is stored in another object with a new name (eqMortalite) the original equation in the database is modified. So be careful if you want to work on equations or matrices from the database without changing them, start by making copies and work on the copy, not on the original object. -remarque : on pourrait le faire en 1 ligne:: +Exercise: +------------ - pop.getNaturalDeathRate().setContent(mortalitenaturelle); +How do you change the selectivity of the gear used by métier métier for population POP? +Ans:: +métier.getGear().getPopulationSelectivity(POP).getEquation() .setContent("return 1;") +How to change the proportion of effort spent by strategy str on métier met in september to 0.1? +Ans:: +str.getStrategyMonthInfo(Month.SEPTEMBER).setProportionMetier(met,0.1); + .. _Modele ISIS-Fish: ../isisFishModel.html