Makumba Developer Documentation

Major makumba components

• The build environment is an Ant script. One single file (build.xml) but still has problems :). Execute ant -projecthelp to see what it can do
• The API, exported to ordinary makumba programmers. Lots of stuff will happen in other parts of makumba, while little should change here. Few classes actually do things in this package, among them MakumbaSystem. Rest are just interfaces, that is,  facades to the rest of the library, exceptions, etc. As a rule, makumba parts described below should use the API to communicate between them, not use classes from the other packages directly.
  
• Handler families. Makumba has all sorts of handlers that achieve different goals (from managing SQL tables to generating HTML content) and need to treat each field type (int, char, date, text, etc) differently. See a chat about this. Handler families derive from org.makumba.abstr.RecordHandler and org.makumba.abstr.FieldHandler. See org.makumba.abstr.printer.RecordPrinter for an example. Handler families can be referred by their package name and their suffix, e.g. org.makumba.abstr.printer.*Printer, where * stands for {Record, Field, int, intEnum, char, date, text,....},. Handler families can be regarded as more complicated classes (a handler family X inherits from another one Y if it's RecordX extends RecordY). Maybe it would be good for future makumba developers to actually transform them into classes since browsing around families of classes can be difficult at first.
• The MDD parser, is the org.makumba.abstr.*Parser handler family. Very rudimentary, an ANTLR-based parser (like the OQL one) could be used. See other things to do about it
• The OQL parser, org.makumba.db.sql.oql, ANTLR-based. The grammar is in the file oql-translator.g. There is quite challenging stuff to do about it if you like to make compilers.
• org.makumba.db.sql contains  the concrete SQL implementation of the makumba database layer (stuff to do). To hack on this package, you will probably need to know how JDBC (Java Database Connectivity) works. Whenever you make a change here, you can test it by executing ant test
• org.makumba.db.sql.Database contains DB configuration code (reading from MakumbaDatabase properties, localhost_mysql_dbname.properties etc)
  
• org.makumba.db.sql.*Manager is the handler family described in the chat , dealing with SQL table management: see if the table in the DB is conform to the MDD and if not create or alter it, do inserts, deletes, updates, etc.
• all table operations are done through org.makumba.db.sql.SQLDBConnection
  
• Besides the handler family, the package contains sqlEngines.properties, with stuff specific for each sql driver, and subpackages such as odbcjet, pgsql, firstsql, etc, containing SQL stuff specific to each of these SQL engines. A SQL-92 standard SQL engine (like mysql) will not need a separate package, maybe just additions to sqlEngines.properties.  There is a description of how to build makumba drivers for other SQL engines
• org.makumba.db.sql.Query is the query caller. Users org.makumba.db.sql.ParameterAssigner  to transform parameters from OQL $x to SQL ? in the right order, and to set them to the JDBC PreparedStatement. To transform parameter data from Makumba to SQL, the *Manager handler family is used (as that one does it anyway for things like inserts and updates). To transform the query results from SQL to Makumba format, also the *Manager family is used by Query. 
• org.makumba.db.sql.SQLUpdate does similar stuff with Query to send UPDATE ... WHERE and DELETE ... WHERE to the database (uses ParameterAssigner to set PreparedStatement parameters, etc).
• org.makumba.dbcontains some abstract stuff about databases, mostly SQL-independent. It should probably be joined with org.makumba.db.sql.  The org.makumba.db.*Handler handler family is the parent of org.makumba.db.sql.*Manager. org.makumba.db.Database represents a generic database, org.makumba.db.Table represents a generic table. org.makumba.db.DBConnection represents a connection to the database, and implements functionalty exported by org.makumba.Database , org.makumba.db.DBConnectionWrapper is an DBConnection that can be given to other classes without risking that those apps will destroy makumba internal structure
• org.makumba.view.jsptaglib is the JSP tag library. To see which mak: tag is implemented by which class, look in servlet-context/makumba.tld. Tag libraries are specified in the JSP 1.2 and Servlet 2.3 standard, see especially javax.servlet.jsp.tagext
• There are plans to completely re-write this package (currently a modest begininig is in org.makumba.view.jsptaglib2) mostly because the "training loops" needed for  mak:list tags to learn about their internal mak:value and mak:list tags are cool, but have problems and are hard to extend. 
• since the JSP specification does not take care of caching,  every MakumbaTag has a TagStrategy. Whenever a new makumba tag is constructed by Tomcat, it looks if a strategy was already cached for it, then  asks the strategy to perform each of the operations. In the future, this may not be needed as modern servlet contexts re-use tag objects that have completed their job instead of destroying them
• mak:list is of course hardest to implement. Root mak:list tags (not contained in any other mak:list or mak:object) have RootQueryStrategy as strategy. Other mak:list tags use QueryStrategy
  
• the org.makumba.view.jsptaglib.*Viewer handler family takes care of displaying different sorts of data in HTML
• makumba forms all inherit from org.makumba.view.jsptaglib.FormTagBase.
  
• org.makumba.viewimplements some generic stuff needed for the taglib. 
• ComposedQuery makes up queries from the from=, where= used in JSP tags. It also knows how to make up bigger queries when a mak:list is embedded in another mak:list
• org.makumba.view.Grouper does the equivalent of a SQL "left join". It's fast enough, but problematic
  
• AttributeParametrizer solves a very difficult problem: not all $attributes in a mak:list query can be transformed in OQL $x parameters. E.g. SELECT blabla ORDER BY $1 is not legal in OQL (or SQL for that matter) but mak:list accepts orderBy="$order", so AP detects that $order is not an OQL parameter.  Threre are rumors that this doesn't work well
• MultipleAttributeParametrizer does a simpler job. Takes vectorial $attributes with variable length and, depending on their length, produces a new OQL query. for example where="a.country IN SET $countries" is  translated to OQL as WHERE a.country IN SET ($1, $2, $3) if 3 countries were selected
• *Formatter is a generic formatter of Makumba data, not dependent on HTML
  
• The controller takes care of invoking business logic when the user interacts with the system. Currently the controller is spread out in various places. They will be moved together in org.makumba.controller
• org.makumba.abstr.Logic  takes care of finding business logic and invoking it. See stuff to do and discuss about business logic
• the http controller takes care of responding to HTML forms and asking org.makumba.abstr.Logic to invoke business logic. See stuff to do
• Each type of form (org.makumba.abstr.view.jsptaglib.NewTag, EditTag) defines a org.makumba.view.jsptaglib.FormResponder  that knows which business logic to invoke
• org.makumba.view.jsptaglib.*Editor knows how to format HTML <input>s and <select>s for each type of Makumba data, and how to read their data from HTTP query strings in form responses
• org.makumba.view.jsptaglib.MultipartHttpParameters reads Http parameters from file upload forms
  
• org.makumba.util contains generic makumba implementation stuff, such as
•  caches: NamedResources  and lately SoftNamedResources 
• LargeData can keep large data in little memory by swapping it to disk (used by large org.makumba.Text as well as mak:lists that produce large output (in org.makumba.view.jsptaglib.RootQueryStrategy). Should also be used by MultipartHttpParameters and the SQL table manager
• MultipleKey provides vectorial keys for caches, used by org.makumba.view.Grouper
• ResourcePool keeps a pool of identical resources. Used for org.makumba.db.DBConenctions
• WrappedException and RuntimeWrappedException are used to transform exception types.
  
• SyntaxPoint is used by the new jsptaglib during parsing of JSPs. It is also thought for use by the a new jspx source viewer.
  
• org.makumba.devel is the makumba developer support, such as MDD, JSP and Java viewers. There are things to improve there.
• documentation is in the doc/ directory, the www.makumba.org website. Can be improved a lot!
• See also general problems with the code