--- /dev/null
+<chapter id="introduction">
+<title>Introduction</title>
+
+<section><title>Architecture overview</title>
+<para>
+ Mir is a fairly large piece of software (over 50.000 lines) written in java.
+It relies on the tomcat servlet framework for administration and open publishing
+tasks. However, unlike many other CMS's that generate html on the fly
+(usually using a cache), Mir writes html pages into a static site.
+Normally, users that visit the mir site, will only see the static site.
+Users that want to publish content (open publishing) will contact
+the dynamic site. Administrators will also contact
+the dynamic site (see figure).
+</para>
+
+<figure><title>mir architecture (single host)</title>
+<mediaobject>
+<imageobject>
+<imagedata fileref="figures/mir-architecture-singlehost.eps" format="EPS"></imagedata></imageobject>
+<imageobject>
+<imagedata fileref="figures/mir-architecture-singlehost.png" format="PNG"></imagedata></imageobject>
+<textobject>
+</textobject>
+</mediaobject>
+</figure>
+
+<para>
+This architecture is interesting because most page requests will be done
+on the static site. Static pages are efficiently handled by the web server.
+It is also interesting because it permits easy mirroring of the static
+site. Mirrors are simple to set up, since only static pages are involved
+(see figure).
+</para>
+
+<figure><title>mir architecture (mirrored)</title>
+<mediaobject>
+<imageobject>
+<imagedata fileref="figures/mir-architecture-mirrored.eps" format="EPS"></imagedata></imageobject>
+<imageobject>
+<imagedata fileref="figures/mir-architecture-mirrored.png" format="PNG"></imagedata></imageobject>
+<textobject>
+</textobject>
+</mediaobject>
+</figure>
+
+</section>
+
+<section><title>Concepts used by Mir</title>
+<para>Here's a list of important terms and concepts used by Mir.
+Many of these concepts will be further detailed later on in this guide.
+</para>
+<glossentry id="producers">
+ <glossterm>producers</glossterm>
+ <glossdef>
+ <para>As mentioned in the architecture overview, mir
+generates a set of static html pages called the static site.
+Generating these pages involves using a template engine to
+replace variables (representing data) in template files. Template files
+are written by web designers.
+In many CMS systems, the available variables (data) are hard-coded into the
+software. In practice, this is often not flexible enough
+for web designers.
+Mir allows designers to request the data they need by using
+the producer framework, configured in the <filename>producers.xml</filename> file.
+</para>
+<para>Originally producers were
+mostly used to generate pages, but they are now used for a lot of
+other tasks. In fact, the <filename>producers.xml</filename> file provides a
+simple, xml-based, programing (scripting) language, so that
+site administrators can script their own custom tasks without
+changing the java code.
+For example, on indymedia.org, producers are used to pull rss
+feeds for the global wire.
+</para>
+<figure><title>An example of article generation with the producers framework</title>
+<mediaobject>
+<imageobject>
+<imagedata fileref="figures/article-generation-example.eps" format="EPS"></imagedata></imageobject>
+<imageobject>
+<imagedata fileref="figures/article-generation-example.png" format="PNG"></imagedata></imageobject>
+<textobject>
+</textobject>
+</mediaobject>
+</figure>
+<para>In the admin web interface, producers appear, for example, on
+the admin->"Generate manually"->"advanced page": (they are called Tasks)</para>
+<para>
+More information on producers is available in <xref linkend="producer_framework" />.
+</para>
+ </glossdef>
+</glossentry>
+
+<glossentry id="database">
+ <glossterm>database access</glossterm>
+ <glossdef>
+ <para>
+Mir uses a postgres database to store it's data.
+Currently, the <code>mir.storage</code>, <code>mircoders.storage</code>,
+<code>mir.entity</code>, and <code>mir.entity.adapter</code>
+packages
+are used to access the database in Mir. However, these packages
+are obsolete and will be replaced by the
+<ulink url="http://www.hibernate.org">hibernate</ulink>
+object/relational persistence system.
+</para>
+ </glossdef>
+</glossentry>
+
+
+<glossentry id="localizer">
+ <glossterm>localizer</glossterm>
+ <glossdef>
+ <para>
+Localizers provide a customization framework that allows
+different mir sites to behave differently. Each site can
+write it's own bits of java code that override default behavior.
+This is effectively
+used by various indymedia sites to customize things
+such open posting mechanisms, open
+posting validation, data model enhancements, etc.
+In other words, the localizer framework provides "hooks"
+where admins can plug in
+their custom code.
+</para>
+<para>
+The <classname>MirLocalizer</classname> interface describes
+the centralized localizer, that may be accessed via the global
+<function>MirGlobal.localizer()</function>
+function. The central localizer provides accessors to
+domain specific localizers
+(like <classname>MirBasicOpenPostingLocalizer</classname>).
+</para>
+<para>
+Default behavior is provided by the <classname>MirBasicLocalizer</classname>
+and it's associated classes. These classes can be extended to
+override default behavior.
+</para>
+<para>
+To override default behavior you must implement a new
+<classname>MirLocalizer</classname>
+and give the path to your class in the
+<code>Mir.Localizer</code> property of the
+<filename>config.properties</filename>
+file.
+</para>
+ </glossdef>
+</glossentry>
+
+<glossentry id="abuse">
+ <glossterm>abuse filter framework</glossterm>
+ <glossdef>
+ <para>
+Mir can be configured to refuse postings or spam. This is done
+by using a set of filters that will attempt to match posted content.
+If any filter matches, appropriate action (FIXME? what action? ) will be taken.
+Three types of filters are currently implemented: IP filters
+(reject certain ip adresses), regular expression filters
+(try to match parts (FIXME? ip? title? content?) of the posting) and
+throttle filters (avoid repeated postings (FIXME? is this ok?)).
+ </para>
+<para>
+Filters may be organized into groups for easier management.
+</para>
+ </glossdef>
+</glossentry>
+
+<glossentry id="generator">
+ <glossterm>generator</glossterm>
+ <glossdef>
+ <para>
+A generator is an abstraction for a template (html template).
+Calling the generator's <function>generate(outputFileWriter,keyValuePairs)</function> method
+will run the template engine on the template file
+and write an output html file.
+Different template engines are
+supported right now:
+<ulink href="http://freemarker.sourceforge.net">freemarker</ulink>
+(used most often), tal (used by some
+sites) and velocity (not used at all but supported anyway).
+</para>
+ </glossdef>
+</glossentry>
+
+
+<glossentry id="logger">
+ <glossterm>logger</glossterm>
+ <glossdef>
+ <para>
+Logging is understood here as "system logs" : information written
+out to files that may be used to track what is going on in Mir,
+especially errors and warnings. Mir uses the <ulink url="http://logging.apache.org/log4j/docs">log4j</ulink> logging system.
+This allows us to split logs into different files, making them
+easier to understand.
+</para>
+ </glossdef>
+</glossentry>
+
+
+<glossentry id="mircoders">
+ <glossterm>mircoders packages</glossterm>
+ <glossdef>
+ <para>
+Originally, the mircoders packages were meant for local developments,
+as opposed to core Mir code. This distinction is now obsolete
+and these packages will probably be reorganized in future releases.
+</para>
+ </glossdef>
+</glossentry>
+
+<glossentry id="bundles">
+ <glossterm>bundles</glossterm>
+ <glossdef>
+ <para>
+A Bundle represents a set key/value pairs stored in a ".properties"
+text file. Bundles are used for internationalization (language
+translations) and for <glossterm linkend="configuration">configuration</glossterm> files (config.properties and
+source/default.properties).
+Bundles may be used to create a template for multiple languages.
+</para>
+ </glossdef>
+</glossentry>
+
+<glossentry id="search">
+ <glossterm>search framework</glossterm>
+ <glossdef>
+ <para>
+Mir's search framework relies on
+<ulink url="http://lucene.apache.org/java/docs/index.html">apache lucene
+</ulink>.
+Content is inserted into a special index file while it is produced
+(see <glossterm linkend="producers">producers</glossterm> framework).
+This allows for quick retreival during search.
+Indexing is requested in the <filename>producers.xml</filename> file
+by the <code><IndexContent></code> node.
+In other words, when Mir generates a static html page for an article,
+it also creates <classname>SearchTerm</classname>'s and inserts
+them into the index.
+By default, the index file is stored in <filename>bin/mir/WEB-INF/index</filename>.
+</para>
+<para>
+Search queries are managed by <function>ServletModuleContent.search()</function>
+Search results are stored by tomcat in
+the user's session for the purposes of pagination and sorting.
+</para>
+<para>
+The design of the indexing and searching make it completely
+independent of the database once the content is indexed.
+</para>
+<para>
+More information is available in <xref linkend="search_framework" />.
+</para>
+ </glossdef>
+</glossentry>
+
+<glossentry id="servlet">
+ <glossterm>servlet framework</glossterm>
+ <glossdef>
+ <para>
+Mir uses the tomcat servlet framework for the admin interface,
+for open posting and for search queries (FIXME something else?).
+Mir exposes two servlets: the <classname>Mir</classname>
+servlet and the <classname>OpenMir</classname> servlet, whose
+methods are directly called in response to an http request.
+For example, a request for <uri>http://somehost.org/mir/servlet/Mir</uri>
+will call the <function>doGet()</function> method of the
+<classname>Mir</classname> class.
+ </para>
+ <para>
+Once requests are received by the
+<classname>Mir</classname> or <classname>OpenMir</classname>
+classes, they are dispatched to other servlet classes.
+The <code>module</code> argument of the http request
+determines the classes name.
+The <code>do</code> argument determines the method's name.
+So
+<uri>http://somehost.org/mir/servlet/Mir?module=Comment&do=list</uri>
+will call <function>ServletModuleComment.list()</function>.
+ </para>
+ </glossdef>
+</glossentry>
+
+
+<glossentry id="media">
+ <glossterm>media framework</glossterm>
+ <glossdef>
+ <para>
+The media framework is quite old and will be thoroughly changed
+in a future release.
+ </para>
+ </glossdef>
+</glossentry>
+
+<glossentry id="configuration">
+ <glossterm>configuration</glossterm>
+ <glossdef>
+ <para>
+Mir is configured through the
+<filename>etc/config.properties</filename> file, which
+overrides default values in
+the
+<filename>source/default.properties</filename> file.
+The key/value pairs are handled by
+<glossterm linkend="bundles">bundles</glossterm>.
+ </para>
+ </glossdef>
+</glossentry>
+
+
+
+
+</section>
+
+
+
+</chapter>
projects / mir.git / blobdiff