doc/developers-guide/introduction.xml

   1 <chapter id="introduction">
   2 <title>Introduction</title>
   3
   4 <section><title>Architecture overview</title>
   5 <para>
   6         Mir is a fairly large piece of software (over 50.000 lines) written in java.
   7 It relies on the tomcat servlet framework for administration and open publishing
   8 tasks. However, unlike many other CMS's that generate html on the fly
   9 (usually using a cache), Mir writes html pages into a static site.
  10 Normally, users that visit the mir site, will only see the static site.
  11 Users that want to publish content (open publishing) will contact
  12 the dynamic site. Administrators will also contact
  13 the dynamic site  (see figure).
  14 </para>
  15
  16 <figure><title>mir architecture (single host)</title>
  17 <mediaobject>
  18 <imageobject>
  19 <imagedata fileref="diagrams/mir-architecture-singlehost.eps" format="EPS"></imagedata></imageobject>
  20 <imageobject>
  21 <imagedata fileref="diagrams/mir-architecture-singlehost.png" format="PNG"></imagedata></imageobject>
  22 <textobject>
  23 </textobject>
  24 </mediaobject>
  25 </figure>
  26
  27 <para>
  28 This architecture is interesting because most page requests will be done
  29 on the static site. Static pages are efficiently handled by the web server.
  30 It is also interesting because it permits easy mirroring of the static
  31 site. Mirrors are simple to set up, since only static pages are involved
  32 (see figure).
  33 </para>
  34
  35 <figure><title>mir architecture (mirrored)</title>
  36 <mediaobject>
  37 <imageobject>
  38 <imagedata fileref="diagrams/mir-architecture-mirrored.eps" format="EPS"></imagedata></imageobject>
  39 <imageobject>
  40 <imagedata fileref="diagrams/mir-architecture-mirrored.png" format="PNG"></imagedata></imageobject>
  41 <textobject>
  42 </textobject>
  43 </mediaobject>
  44 </figure>
  45
  46 </section>
  47
  48 <section><title>Concepts used by Mir</title>
  49 <para>Here's a list of important terms and concepts used by Mir.
  50 Many of these concepts will be further detailed latter on in this guide.
  51 </para>
  52 <glossentry id="producers">
  53   <glossterm>producer</glossterm>
  54     <glossdef>
  55           <para>As mentioned in the architecture overview, mir
  56 generates a set of static html pages called the static site.
  57 Generating these pages involves using a template engine to
  58 replace variables (representing data) in template files. Template files
  59 are written by web designers.
  60 In many CMS systems, the available variables (data) are hard-coded into the
  61 software. In practice, this is often not flexible enough
  62 for web designers.
  63 Mir allows designers to request the data they need by using
  64 the producer framework, configured in the "producers.xml" file.
  65 </para>
  66 <para>Originally producers were
  67 mostly used  to generate  pages, but  they are now used  for a  lot of
  68 other  tasks. In fact, the producers.xml file provides a
  69 simple, xml-based, programing (scripting) language, so that
  70 site administrators can script their own custom tasks without
  71 changing the java code.
  72 For example, on indymedia.org, producers are used to pull rss
  73 feeds  for the  global wire.
  74 </para>
  75 <figure><title>An example of article generation with the producers framework</title>
  76 <mediaobject>
  77 <imageobject>
  78 <imagedata fileref="diagrams/article-generation-example.eps" format="EPS"></imagedata></imageobject>
  79 <imageobject>
  80 <imagedata fileref="diagrams/article-generation-example.png" format="PNG"></imagedata></imageobject>
  81 <textobject>
  82 </textobject>
  83 </mediaobject>
  84 </figure>
  85 <para>
  86 Further information on producers may be found at XXX and in the javadoc
  87 (classes Producer, NodedProducer, roducerNode...).
  88 </para>
  89         </glossdef>
  90 </glossentry>
  91
  92 <glossentry id="database">
  93   <glossterm>database</glossterm>
  94     <glossdef>
  95           <para>
  96 Mir uses a postgres database to store it's data.
  97 Currently, the mir.storage, mircoders.storage, mir.entity, and
  98 mir.entity.adapter
  99 packages
 100 are used to acces  the database in Mir. However, these packages
 101 are obsolete and will be replaced by the
 102 <ulink url="http://www.hibernate.org">hibernate</ulink>
 103 object/relational persistence system.
 104 </para>
 105         </glossdef>
 106 </glossentry>
 107
 108
 109 <glossentry id="localizer">
 110   <glossterm>localizer</glossterm>
 111     <glossdef>
 112           <para>
 113 FIXME localizers are to allow mir installations to add code seperate from the
 114 main code. A lot of things can be changed in an installation (and are
 115 by various mir sites). Think of custom open posting mechanism, open
 116 posting validation, data model enhancements.
 117 </para>
 118         </glossdef>
 119 </glossentry>
 120
 121 <glossentry id="generator">
 122   <glossterm>generator</glossterm>
 123     <glossdef>
 124           <para>
 125 A generator is an abstraction for a template engine.
 126 Different template engines are
 127 supported right now:
 128 <ulink href="http://freemarker.sourceforge.net">freemarker</ulink>
 129 (used most often), tal (used by some
 130 sites) and velocity (not used at all but supported anyway).
 131 </para>
 132         </glossdef>
 133 </glossentry>
 134
 135
 136 <glossentry id="logger">
 137   <glossterm>logger</glossterm>
 138     <glossdef>
 139           <para>
 140 Logging is understood here as "sytem logs" : information written
 141 out to files that may be used to track what is going on in Mir,
 142 especially errors and warnings. Mir uses the <ulink href="http://logging.apache.org/log4j/docs">log4j</ulink> logging system.
 143 This alows us to split logs into different files, making them
 144 easier to understand.
 145 </para>
 146         </glossdef>
 147 </glossentry>
 148
 149 <glossentry id="mircoders">
 150   <glossterm>mircoders packages</glossterm>
 151     <glossdef>
 152           <para>
 153 Originally, the mircoders packages were meant for local developpements,
 154 as opposed to the core Mir code. This distinction is now obsolete
 155 and these packages will probably be reorganized in future releases.
 156 </para>
 157         </glossdef>
 158 </glossentry>
 159
 160 <glossentry id="bundle">
 161   <glossterm>bundles</glossterm>
 162     <glossdef>
 163           <para>
 164 bundles are key/value pairs in a text file, used for configuration
 165 and internationalization
 166 </para>
 167         </glossdef>
 168 </glossentry>
 169
 170
 171
 172 </section>
 173
 174
 175
 176 </chapter>