--------------------------------------------------------------------------------------
+-------------------------------------------------------------------------------
A short intro to the code-structure of Mir
--------------------------------------------------------------------------------------
+-------------------------------------------------------------------------------
In the java-source tree you will find the following:
Servlets:
--------------------------------------------------------------------------------------
+-------------------------------------------------------------------------------
-Looking from the request of a client browser onto MIR, the http-request is passed
-via Apache/Tomcat to either Mir.class or OpenMir.class. Mir.class handles all
-request that deal with internal administration tasks of MIR. OpenMir is the
-Servlet that deals with all open tasks: adding comments or articles/media to
-the system.
+Looking from the request of a client browser onto MIR, the http-request is
+passed via Apache/Tomcat to either Mir.class or OpenMir.class. Mir.class
+handles all request that deal with internal administration tasks of MIR.
+OpenMir is the Servlet that deals with all open tasks: adding comments or
+articles/media to the system.
-These servlets don't do much but dispatching the tasks to an underlying code
-level, called ServletModules. OpenMir.class is basically a special case of Mir.class,
-no authentication is needed, and only two underlying ServletModule are used.
+These servlets don't do much but dispatching the tasks to an underlying
+code level, called ServletModules. OpenMir.class is basically a special
+case of Mir.class, no authentication is needed, and only two underlying
+ServletModule are used.
-The following explanation is about how requests are passed through, and responses
-to the client-browser are generated. The request has to pass through up to four
-levels of code (and from there asking the database), until it collected all the
-necessary data or performed all necessary tasks, to be able to respond.
+The following explanation is about how requests are passed through, and
+responses to the client-browser are generated. The request has to pass
+through up to four levels of code (and from there asking the database),
+until it collected all the necessary data or performed all necessary
+tasks, to be able to respond.
ServletModules:
--------------------------------------------------------------------------------------
-
-The ServletModules are called via reflection java-api. The http-request parameter
-"module=XXX" and "do=YYY" are evaluated. A method YYY(HttpRequest,HttpResponse) is
-called in ServletModuleXXX.
-
+-------------------------------------------------------------------------------
+
+The ServletModules are called via reflection java-api. The http-request
+parameter "module=XXX" and "do=YYY" are evaluated. A method
+YYY(HttpRequest,HttpResponse) is called in ServletModuleXXX.
+
+A common mistake for those new to Java is to look for usage of a class in
+the code by doing a "grep -r ClassName" or something like that. In this
+case, grep -r ServletModuleImages for example will turn up nothing except
+for ServletModuleImages itself.. that is because of reflection as
+explained above.
+
+The media handlers in mir.media.* work the same way as well.
+
+ Database/Entity:
+-------------------------------------------------------------------------------
+- db: singeltons, object-representation of db-table, *low-level* access,
+generating entities, does all the dirty JDBC work. There is a Database
+Class for every table in the DB.
+
+If an Entity wants to store itself in the media table, it has to have a
+storage object of type DatabaseMedia....
+
+When you ask a storage object to get something, it hands back an Entity.
+[through Database*.selectByWhereClause(), selectById().]
+
+- entity: representation of row. Contains the contents of "select * from
+dbname where id=rowid" in a HashMap. accessible via
+Entity.getValue("keyname"). One can do Entity.setValue(...,
+Entity.update() which syncs the Hash with the DB row and Entity.insert()
+to insert the HashMap as a new row, etc... basically high level DB access.
+The text component of an article is an entity (EntityContent, a row from
+the content table.) In short this is how we fetch content (whatever that
+may be: actual data, media meta-data, media_types, etc..) from the DB and
+write to the DB. Everything has to be reprented as an Entity.
+
+All Entities must have a StorageObject (theStorage) which is a Database
+object of the appropriate type. it is the connection between the entity
+data and the DB table itself. The only way to get an Entity other than
+asking a storage object to fetch one is to construct one by passing the
+storage object to the Entity Konstruktor.
+
+There is also EntityList, a list of entities..
Modules:
--------------------------------------------------------------------------------------
-
-
-Database/Entity:
--------------------------------------------------------------------------------------
-- db: singeltons, object-representation of db-table, access, generating entities
-- entity: representation of row
-
+-------------------------------------------------------------------------------
+
+- This one is a little grey... It's pretty much a wrapper around Database
+and Entity combined, so it's a half level higher up or so. It's not always
+necessary to use/have a Module either.. A usage example: you can do
+ModuleName.getByWhereClause() and it returns a list of Entities that match
+the query. Like entities you must have a StorageObject to access the DB.
+but unlike Entity, you can start out without one. Modules use Entity and
+Database objects internally. [Actually it uses Database object internally
+and returns Entitys...]
+
+Also I believe the intention was/is that it should be used in place of
+Entity for any *logic* that would normally have to into an Entity as
+Entity should be free of a case specific logic in theory. But that's not
+always true if you use EntityImages as an example, but that seems to be
+because EntityImages needs low-level DB connections.
Producer
--------------------------------------------------------------------------------------
\ No newline at end of file
+-------------------------------------------------------------------------------
+
+Well, what makes Mir different than other Content Management Systems is
+that it does not generate the content pages dynamically or use simple
+caching methods. Rather it generates static .[s]html files exclusively.
+This makes mir very fast under high viewing loads as it does not use
+servlets for this at all. It also makes it very easy to mirror as the
+mirrors do not have to run any Mir code, they only have to have a static
+webserver. In fact the first site to use Mir, germany.indymedia.org is on
+a whole other machine on another continent than the machine that
+*produces* the static files. Germany.indymedia.org already has 3 mirrors.
+
+The mircoders.producer.* classes are responsible for creating these static
+.html files and the filesystem structure that they reside in. This
+includes files that are article summaries and files that are the whole
+article themselves. Some media types also require Producers.
+
+If the main content *viewing* server is on another host, the FS tree is
+then rsync'ed to the viewing host.
+
+The Producers are called exclusively from the ServletModules in
+mircoders.servlet.*. They are called when a new article/comment is added,
+or when an administrator/moderator makes modifications to the site or when
+a manual update is desired. The method "handle()" is the one that does all
+work it takes parameters that tell it to force update all files even if
+their contents is unchanged, etc.. some Producers take an article ID as an
+argument telling them to create the html page representing the article and
+any summary pages that might be changed due to the addition of the
+article.
+
+Producers of course use Entities, Database, MediaHandler and Module
+objects internally.
+
+A dB field called is_produced is used to determine wether or not an Object
+needs to be produced.
+
+Oh and before I forget, it generates the pages based on a template. It
+uses the Freemarker templating system. Doc on freemarker is available at
+freemarker.sourceforge.net I believe.
+
+TODO: In theory it would be cool if we could abstract the output mechanism
+further to use other types of templates and to generate content other than
+HTML (like WAP for example).
+
+Media Handlers
+-------------------------------------------------------------------------------
+They are kind of helper classes to deal with different representations of
+media types. They are called via the java reflection API. The class names
+are resolved through the media_type table. See
+source/mir/media/MirMedia.java for documentation.
+
+Helper classes
+-------------------------------------------------------------------------------
+mir.misc.* (source/mir/misc/*) contains a bunch of classes that do Regexp,
+file handling and those sorts of things. Always look here first before
+writing such a thing.
projects / mir.git / commitdiff