====== Architectural Description Tool ======

===== Context =====

This tools aims to describe the global jSeduite infrastructure. The first usage is to automatically generate diagrams from the description. Others application can use this representation to automate the generation of bundles, ...

The underlying engine is the Prolog inference engine, which provides a very efficient backend for this kind of job.

===== Describing the architecture =====

The architecture description file is named ''[[http://code.google.com/p/jseduite/source/browse/trunk/architecture/description/jSeduite.pl|jSeduite.pl]]'', in the ''$JSEDUITE_HOME/architecture/description'' folder.

You'll describe the jSeduite architecture by expressing a set of logical facts. The facts syntax is really simple, and the only thing you have to know is you can't use a name which starts by an upper case character. 

The following list contains all available facts, and the corresponding semantic :
 
  * Entities: 
    * ''library(X)'' <=> ''X'' is a library
    * ''table(X)'' <=> ''X'' is a table inside the jSeduite database
    * ''view(X)'' <=> ''X'' is a view inside the jSeduite database (''table'' includes ''view'')
    * '' webservice(X)'' <=> ''X'' is defined as a black box web service inside jSeduite
    * ''orchestration(X)'' <=> ''X'' is an orchestration (''webservice'' includes ''orchestration'')
  * Links: 
    * ''depends(X,Y)'' <=> ''library(X)'', ''library(Y)'', ''X'' uses a method defined in ''Y''
    * ''references(A,B)'' <=> ''table(A)'', ''table(B)'' and ''A'' defines a reference to ''B''
    * ''provides(X,O)'' <=> ''webservice(X)'' and ''X'' provides an operation named ''O''
    * ''uses(X,Y)'' <=> ''webservice(X)'', ''table(Y)'' and ''X'' retrieve data from ''Y''
    * ''loads(X,Y)'' <=> ''webservice(X)'', ''library(Y)'', ''X'' use functionalities from ''Y''
    * ''usesAsPartner(X,Y)'' <=> ''orchestration(X)'', ''webservice(Y)'', ''Y'' is a partner of ''X''

===== Extracting diagrams =====

The ''arch_gen.sh'' shell script can generate graphviz diagrams from this representation.

  * Computing the //big picture// into ''out.png'': 
    * ''./arch_gen.sh''
  * Computing the //big picture// into ''f.png'': 
    * ''./arch_gen.sh f.png''
  * Computing a predefined diagram: 
    * ''./arch_gen.sh orchestrations.png orch_arch''
    * ''./arch_gen.sh webservices.png orch_arch''
  * Computing a dependencies graph: 
    * ''./arch_gen.sh cachedFeedReader.png "dgraph([cachedFeedReader])"''

===== Extracting dependency graph from Website =====

The ''[[http://code.google.com/p/jseduite/source/browse/trunk/architecture/arch_gen.php|arch_gen.php]]'' script bind prolog to php and allow dynamic generation of dependency graph.

==== Installing the script ====

You'll just have to retrieve the raw script from here: [[http://jseduite.googlecode.com/svn/trunk/architecture/arch_gen.php|arch_gen.php]]. 

<note bloquante>
As the web script will //automagically// synchronize its descriptor from the SVN repository, the ''www'' user **MUST** be able to write data inside the folder you're using.
</note>

Then, open the script and specialize it for your own web server, by editing the three following constants: 
<code php>
define("SWIPL","/opt/local/bin/swipl");
define("NEATO","/sw/bin/neato");
define("FONT_PATH","/System/Library/Fonts");
</code>
 
  * ''SWIPL'' => path of the SWI prolog interpreter
  * ''NEATO'' => path of the ''neato'' command
  * ''FONT_PATH'' => path where usual fonts are stored on your system

==== Running the script ====

Assuming you've deploy the script inside a folder available at the URL ''http://server.domain/arch_gen.php'':

  * Dynamically inside a web browser: 
    * Just use the following url: ''http://server.domain/arch_gen.php?target=entity''
  * From a plain HTML page: 
<code html>
<div align="center" >
  <img src="http://server.domain/arch_gen.php?target=entity" />
</div>
</code>
  * From a dokuwiki page: 
    * External images are well supported inside dokuwiki, *Excepting** when the URL contains optional arguments. So, you'll need to allow html code from the admin interface, and then use the following syntax: 
<file>
<html>
  <div align="center" >
    <img src="http://server.domain/arch_gen.php?target=entity" />
  </div>
</html>
</file>

<note tuyau>
For this website, the script is reachable here: ''[[http://www.jseduite.org/webarch_gen/arch_gen.php?target=]]''
</note>