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="figures/mir-architecture-singlehost.eps" format="EPS"></imagedata></imageobject>
  20 <imageobject>
  21 <imagedata fileref="figures/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="figures/mir-architecture-mirrored.eps" format="EPS"></imagedata></imageobject>
  39 <imageobject>
  40 <imagedata fileref="figures/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 later on in this guide.
  51 </para>
  52 <glossentry id="producers">
  53   <glossterm>producers</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 <filename>producers.xml</filename> 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 <filename>producers.xml</filename> 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="figures/article-generation-example.eps" format="EPS"></imagedata></imageobject>
  79 <imageobject>
  80 <imagedata fileref="figures/article-generation-example.png" format="PNG"></imagedata></imageobject>
  81 <textobject>
  82 </textobject>
  83 </mediaobject>
  84 </figure>
  85 <para>In the  admin web interface,  producers appear, for  example, on
  86 the admin->"Generate manually"->"advanced page": (they are called Tasks)</para>
  87 <para>
  88 More information on producers is available in  <xref linkend="producer_framework" />.
  89 </para>
  90         </glossdef>
  91 </glossentry>
  92
  93 <glossentry id="database">
  94   <glossterm>database access</glossterm>
  95     <glossdef>
  96           <para>
  97 Mir uses a postgres database to store it's data.
  98 Currently, the <code>mir.storage</code>, <code>mircoders.storage</code>,
  99 <code>mir.entity</code>, and <code>mir.entity.adapter</code>
 100 packages
 101 are used to access  the database in Mir. However, these packages
 102 are obsolete and will be replaced by the
 103 <ulink url="http://www.hibernate.org">hibernate</ulink>
 104 object/relational persistence system.
 105 </para>
 106         </glossdef>
 107 </glossentry>
 108
 109
 110 <glossentry id="localizer">
 111   <glossterm>localizer</glossterm>
 112     <glossdef>
 113           <para>
 114 Localizers provide a customization framework that allows
 115 different mir sites to behave differently. Each site can
 116 write it's own bits of java code that override default behavior.
 117 This is effectively
 118 used by various indymedia sites to customize things
 119 such  open posting mechanisms, open
 120 posting validation, data model enhancements, etc.
 121 In other words, the localizer framework provides "hooks"
 122 where admins can plug in
 123 their custom code.
 124 </para>
 125 <para>
 126 The <classname>MirLocalizer</classname> interface describes
 127 the  centralized localizer, that may be accessed via the global
 128 <function>MirGlobal.localizer()</function>
 129 function. The central localizer provides accessors to
 130 domain specific localizers
 131 (like <classname>MirBasicOpenPostingLocalizer</classname>).
 132 </para>
 133 <para>
 134 Default behavior is provided by the <classname>MirBasicLocalizer</classname>
 135 and it's associated classes. These classes can be extended to
 136 override default behavior.
 137 </para>
 138 <para>
 139 To override default behavior you must implement a new
 140 <classname>MirLocalizer</classname>
 141 and give the path to your class in the
 142 <code>Mir.Localizer</code> property of the
 143 <filename>config.properties</filename>
 144 file.
 145 </para>
 146         </glossdef>
 147 </glossentry>
 148
 149 <glossentry id="abuse">
 150   <glossterm>abuse filter framework</glossterm>
 151     <glossdef>
 152           <para>
 153 Mir can be configured to refuse postings or spam. This is done
 154 by using a set of filters that will attempt to match posted content.
 155 If any filter matches, appropriate action (FIXME? what action? ) will be taken.
 156 Three types of filters are currently implemented: IP filters
 157 (reject certain ip adresses), regular expression filters
 158 (try to match parts (FIXME? ip? title? content?) of the posting) and
 159 throttle filters (avoid repeated postings (FIXME? is this ok?)).
 160           </para>
 161 <para>
 162 Filters may be organized into groups for easier management.
 163 </para>
 164         </glossdef>
 165 </glossentry>
 166
 167 <glossentry id="generator">
 168   <glossterm>generator</glossterm>
 169     <glossdef>
 170           <para>
 171 A generator is an abstraction for a template (html template).
 172 Calling the generator's <function>generate(outputFileWriter,keyValuePairs)</function> method
 173 will run the template engine on the template file
 174 and write an output html file.
 175 Different template engines are
 176 supported right now:
 177 <ulink href="http://freemarker.sourceforge.net">freemarker</ulink>
 178 (used most often), tal (used by some
 179 sites) and velocity (not used at all but supported anyway).
 180 </para>
 181         </glossdef>
 182 </glossentry>
 183
 184
 185 <glossentry id="logger">
 186   <glossterm>logger</glossterm>
 187     <glossdef>
 188           <para>
 189 Logging is understood here as "system logs" : information written
 190 out to files that may be used to track what is going on in Mir,
 191 especially errors and warnings. Mir uses the <ulink url="http://logging.apache.org/log4j/docs">log4j</ulink> logging system.
 192 This allows us to split logs into different files, making them
 193 easier to understand.
 194 </para>
 195         </glossdef>
 196 </glossentry>
 197
 198
 199 <glossentry id="mircoders">
 200   <glossterm>mircoders packages</glossterm>
 201     <glossdef>
 202           <para>
 203 Originally, the mircoders packages were meant for local developments,
 204 as opposed to core Mir code. This distinction is now obsolete
 205 and these packages will probably be reorganized in future releases.
 206 </para>
 207         </glossdef>
 208 </glossentry>
 209
 210 <glossentry id="bundles">
 211   <glossterm>bundles</glossterm>
 212     <glossdef>
 213           <para>
 214 A Bundle represents a set  key/value pairs stored in a ".properties"
 215 text  file.  Bundles  are used  for  internationalization (language
 216 translations)  and for  <glossterm linkend="configuration">configuration</glossterm>  files (config.properties and
 217 source/default.properties).
 218 Bundles  may be used to create a template for multiple languages.
 219 </para>
 220         </glossdef>
 221 </glossentry>
 222
 223 <glossentry id="search">
 224   <glossterm>search framework</glossterm>
 225     <glossdef>
 226           <para>
 227 Mir's search framework relies on
 228 <ulink url="http://lucene.apache.org/java/docs/index.html">apache lucene
 229 </ulink>.
 230 Content is inserted into a special index file while it is produced
 231 (see <glossterm linkend="producers">producers</glossterm> framework).
 232 This allows for quick retreival during search.
 233 Indexing is requested in the <filename>producers.xml</filename> file
 234 by the <code>&lt;IndexContent&gt;</code> node.
 235 In other words, when Mir generates a static html page for an article,
 236 it also creates <classname>SearchTerm</classname>'s and inserts
 237 them into the index.
 238 By default, the index file is stored in <filename>bin/mir/WEB-INF/index</filename>.
 239 </para>
 240 <para>
 241 Search queries are managed by <function>ServletModuleContent.search()</function>
 242 Search results are stored by tomcat in
 243 the user's session for the purposes of pagination and sorting.
 244 </para>
 245 <para>
 246 The design of the indexing and searching make it completely
 247 independent of the database once the content is indexed.
 248 </para>
 249 <para>
 250 More information  is available in <xref linkend="search_framework" />.
 251 </para>
 252         </glossdef>
 253 </glossentry>
 254
 255 <glossentry id="servlet">
 256   <glossterm>servlet framework</glossterm>
 257     <glossdef>
 258           <para>
 259 Mir uses the tomcat servlet framework for the admin interface,
 260 for open posting and for search queries (FIXME something else?).
 261 Mir exposes two servlets: the <classname>Mir</classname>
 262 servlet and the <classname>OpenMir</classname> servlet, whose
 263 methods are directly called in response to an http request.
 264 For example, a request for <uri>http://somehost.org/mir/servlet/Mir</uri>
 265 will call the <function>doGet()</function> method of the
 266 <classname>Mir</classname> class.
 267           </para>
 268           <para>
 269 Once requests are received by the
 270 <classname>Mir</classname> or <classname>OpenMir</classname>
 271 classes, they are dispatched to other servlet classes.
 272 The <code>module</code> argument of the http request
 273 determines the classes name.
 274 The <code>do</code> argument determines the method's name.
 275 So
 276 <uri>http://somehost.org/mir/servlet/Mir?module=Comment&amp;do=list</uri>
 277 will call <function>ServletModuleComment.list()</function>.
 278       </para>
 279         </glossdef>
 280 </glossentry>
 281
 282
 283 <glossentry id="media">
 284   <glossterm>media framework</glossterm>
 285     <glossdef>
 286           <para>
 287 The media framework is quite old and will be thoroughly changed
 288 in a future release.
 289       </para>
 290         </glossdef>
 291 </glossentry>
 292
 293 <glossentry id="configuration">
 294   <glossterm>configuration</glossterm>
 295     <glossdef>
 296           <para>
 297 Mir is configured through the
 298 <filename>etc/config.properties</filename> file, which
 299 overrides default values in
 300 the
 301 <filename>source/default.properties</filename> file.
 302 The key/value pairs are handled by
 303 <glossterm linkend="bundles">bundles</glossterm>.
 304       </para>
 305         </glossdef>
 306 </glossentry>
 307
 308
 309
 310
 311 </section>
 312
 313
 314
 315 </chapter>