makumba

• {@link org.makumba.db.sql.mysql}
• {@link org.makumba.db.sql.informix}
• {@link org.makumba.db.sql.odbcjet}

The Makumba JSP rendering engine

• page identification: it is impossible to know which page has a tag been declared in. It is possible to find out which page has been requested, but if that page includes other pages, there is no way to find out if the tag is in an included file or not. The tomcat-dependent class {@link org.makumba.view.jsptaglib.TomcatJsp} solves the problem
• page analysis: JSP provides a way to get access to an XML image of the JSP file, but whatever analysis is done there is not accessible to the tags at page runtime
  
• tag identification: the javax.servlet.jsp.tagext.Tag class has no way of identifying itself (e.g. it knows that "I'm a mak:list tag" but it does not know "I am the mak:list query from file F, line C, column L, my constant attributes are as follows: from=... where=....,  I contain the following mak:list tags.... and the following mak:value tags:...., my mak:list parent is ...., therefore my query will be: .... ". This problem is solved by parsing the JSP page in classes like {@link org.makumba.util.JspParseData} and  {@link org.makumba.view.jsptaglib.MakumbaJspAnalyzer }
• communication between instances of the same tag: if two javax.server.jsp.tagext.Tag represent the same physical tag executing at different times within the same request, it is impossible for the first to leave some data for the other to pick up on and continue

Terms used for taglib implementation

• iteration: an iteration of a mak:list (or mak:object, below all references to mak:list also stand for mak:object)
• parentList: below, A is the parent mak:list of B  (same goes for any combination of mak:list and mak:object)
  

  <mak:list A > 
  ...<some:otherTagThatIsNotMakListOrObject C > ...
     <mak:list B> 
     ...
     </mak:list> 
  ...</some:otherTagThatIsNotMakListOrObject> ...
  </mak:list> 
  

• rootList: a mak:list that has no parentList
  
• parentIteration: an iteration of the parentList of the mak:list.
  parentIterations are important because the object that represents the mak:list (of type {@link org.makumba.view.jsptaglib.QueryTag} ) changes between one parent iteration and another. Due to that, makumba must keep somewhere the data iterated by a mak:list, and retrieve it at each parentIteration.
• iterationGroup: all iterations of a mak:list that are done within the same parentIteration (by the same {@link org.makumba.view.jsptaglib.QueryTag})
• listQuery: every mak:list from the page produces a query.
  The query is executed only once (if not repeated via some scriplet), no matter how many parent iterations there are.
• parentQuery: queries are derived from the query of the parent mak:list tag, by adding the FROM and WHERE sections. This is done in {@link org.makumba.view.ComposedQuery}
• listData: the results of the listQuery
• iterationGroupData: the part of the listData that is iterated through during an iterationGroup
• nullableValueQuery: if a mak:value or mak:input (mentioned only as mak:value in what follows) has an expression of the form label.ptr1.ptr2.ptr3.field and any of ptr1...N is nullable, that mak:value will introduce a separate query, whose parentQuery is the listQuery of the parent mak:list. Consider the following example

  RestaurantCook.mdd
    person = not null ptr Person
    favoriteDish = ptr Dish ; NULLABLE!
  
  cookView.jsp
    <mak:list from="general.RestaurantCook rc" />
      <mak:value expr="rc.person.name" />
     <mak:value expr="rc.favoriteDish.name" />
    </mak:list>
  

  If there would be a single query, then the cooks who have no favoriteDish pointer filled in (nullable, so it's possible) would not be returned by the list query (simplified notation):
  

    SELECT p.name, d.name
    FROM   RestaurantCook rc, Person p, Dish d
    WHERE  rc.person = p AND rc.favoriteDish = d ;
  

  because the where condition "rc.favoriteDish = d" cannot be fulfilled for those cooks that have rc.favoriteDish = NIL. So instead you do the listQuery:
  

    SELECT p.name
    FROM   RestaurantCook rc, Person p
    WHERE  rc.person = p ;
  

  and the nullableValueQuery:
  

    SELECT p.name, d.name
    FROM   RestaurantCook rc, Person p, Dish d
    WHERE  rc.person = p AND rc.favoriteDish = d ;

  All mak:value's whose expression is nullable due to the same pointer should be computed as projections in the same nullableValueQuery.
  

• setFieldValueQuery: if a mak:value or mak:input has an expression of the form label.ptr1...ptrN.setField, that mak:value
  will introduce a separate query whose parent is the listQuery of the parent mak:list. setFieldValueQueries are especially used to generate HTML <select> for mak:inputs
  
• valueQuery: a nullableValueQuery or setFieldValueQuery
• queryMak:value: mak:value/input that does generates a valueQuery, i.e. a query that is forced not by the mak:list per-se, but because of the special data type of the projections
• nonQueryMak:value: mak:value/input that does not generate a valueQuery
• valueProjection: a query projection that corresponds to an nonQueryMak:value.
  Basically every nonQueryMak:value needs to know which query it should read its result from, and which projection (column) of that query corresponds to that nonQueryMak:value . The queryMak:values need to know their valueQuery. In addition queryMak:values that introduce nullableValueQueries also need to know which projection of the nullableValueQuery corresponds to them, because a nullableValueQuerymay be shared by more mak:values
  
• listGroup: a rootList and all the children mak:lists and mak:values. The rootList has no parent, this is equivalent to having one single parentIteration. So the {@link org.makumba.view.jsptaglib.QueryTag} of a rootList will never change due to parentIterations. That makes it a good candidate to store the data of all its enclosed listQueries and valueQueries. Before storing them, it must execute the queries. So the rootList of the listGroup will execute all the listQueries and valueQueries.
• queryProjection: a column selected in a query (i.e. between SELECT and FROM, comma-separated)
• currentListData: the data row (all queryProjections) from the current iteration of a mak:list or mak:object. Also referred to as the data of an iteration
  
• currentDataSet: a stack containing the the currentListData of each listQuery that is currently iterating: the data of the current iteration, the data of the parentIteration... and finally the currentDataSet of the rootList at the bottom of the stack. A  mak:list will push its current result in the stack at the begining of each iteration, and will pop it out at the end.
• keyLabels: the labels declared in the FROM of a query

<mak:object from="best.johnny.Season ssn" where="ssn.name = $season" >

• keyProjections: queryProjections made from keyLabels.
  The keyLabels are always (i think) selected as projections, whether they are requested in mak:values or not. All key projections selected in a parent are selected in the children, but not the reverse.
  
• The rule of the query rendering engine:
  In a currentDataSet, the value of a keyProjection in a listQuery currentListData is equal to the value of that keyProjection in the parentQuery
  currentListData, if it is selected there.
  
• grouping: to determine an iterationGroupData from a listData (which a {@link org.makumba.view.jsptaglib.QueryTag} should do when it starts), one has to choose all rows from the list data that have the keyProjections equal to those currently iterated by the parentQueriesas stored in the
  currentDataSet. This is done with the help of class {@link org.makumba.view.Grouper}.
  

	<mak:list from="lbg l"><mak:value "l.name"/> 
  		<mak:list from="members m" where="m.homeLbg = l">
		<mak:value "m.firstName" />
  		</mak:list>
	</mak:list>

	1/ SELECT l, l.name from Lbg l
	2/ SELECT l, l.name, m.firstName from Lbg l, Members m WHERE m.homeLbg=l ; 

// at group list start
Grouper listDataGrouper= new Grouper(dataAboutKeys, listData)

// then, for every parent iteration
iterationGroupData=listDataGrouper.getData(currentDataSet)

• to determine a value displayed by queryMak:value, we need to apply the same pattern
  

	valueQueryData=grouper(valueQueryResult, currentDataSet)

• tagKey: a key that uniquely identifies a mak:list/object or mak:value/input/editForm tag within the page. The key is made from the tag attributes that cannot cahnge at execution time (mak:list from, where, orderBy, mak:value expr) and the key of the parentList. They key is used for the mak:list/valueto find its listData at the begining of a parentIteration (from which it computes the iterationGroupData), by mak:value/input/editForm to find their value in the iterationGroupData of the parentList (for nonQueryMak:values) or of their own valueQuery
  
• queryKey: a key that uniquely identifies a listQuery or valueQuery within the page. The querykey of listQueries is the same with their mak:list tagKey. The queryKey of  a valueQuery is the queryKey of the parentList plus the path to the nullable pointer that lead to the creation of the nullableValueQuery (this ensures that values that are nullable due to the same pointer will share the same query) or the set field for setValueQuery.
  

Currently relies on {@link junit.framework}, but additional types of tests will probably need additional testing methods. Testing {@link org.makumba.view.jsptaglib} seems much more difficult and will be probably done with Cactus.