1 <chapter id="introduction">
2 <title>Introduction</title>
4 <section><title>Architecture overview</title>
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).
16 <figure><title>mir architecture (single host)</title>
19 <imagedata fileref="../diagrams/mir-architecture-singlehost.eps" format="EPS"></imagedata></imageobject>
21 <imagedata fileref="../diagrams/mir-architecture-singlehost.png" format="PNG"></imagedata></imageobject>
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
35 <figure><title>mir architecture (mirrored)</title>
38 <imagedata fileref="../diagrams/mir-architecture-mirrored.eps" format="EPS"></imagedata></imageobject>
40 <imagedata fileref="../diagrams/mir-architecture-mirrored.png" format="PNG"></imagedata></imageobject>
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.
52 <glossentry id="producers">
53 <glossterm>producer</glossterm>
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
63 Mir allows designers to request the data they need by using
64 the producer framework, configured in the "producers.xml" file.
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.
75 <figure><title>An example of article generation with the producers framework</title>
78 <imagedata fileref="../diagrams/article-generation-example.eps" format="EPS"></imagedata></imageobject>
80 <imagedata fileref="../diagrams/article-generation-example.png" format="PNG"></imagedata></imageobject>
86 Further information on producers may be found at XXX and in the javadoc
87 (classes Producer, NodedProducer, roducerNode...).
92 <glossentry id="database">
93 <glossterm>database</glossterm>
96 Mir uses a postgres database to store it's data.
97 Currently, the mir.storage, mircoders.storage, mir.entity, and
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.
109 <glossentry id="localizer">
110 <glossterm>localizer</glossterm>
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.
121 <glossentry id="generator">
122 <glossterm>generator</glossterm>
125 A generator is an abstraction for a template engine.
126 Different template engines are
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).
136 <glossentry id="logger">
137 <glossterm>logger</glossterm>
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.
149 <glossentry id="mircoders">
150 <glossterm>mircoders packages</glossterm>
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.
160 <glossentry id="bundle">
161 <glossterm>bundles</glossterm>
164 bundles are key/value pairs in a text file, used for configuration
165 and internationalization