sábado, 25 de abril de 2009

Y hablando de diseño de APIs...

Hay que ver esta presentación de Joshua Bloch: How to design a good API and why it matters . Es fabulosa.

miércoles, 22 de abril de 2009

Leyendo XML en Java sin dolor

Leer XML en Java es un verdadero pain in the ass, a diferencia de Scala, que tiene soporte nativo para XML. No estoy muy al tanto de librerías que facilitan la tarea, que las debe haber, pero quiero compartir una muy elemental que hice. Las características de su diseño que, creo, la hacen interesante son:
  • Inmutabilidad
  • Acceso a subnodos por invocaciones encadenadas, evitando NPE ante nodos inexistentes
El primer punto es una verdad a medias, porque se encapsula un org.w3c.dom.Node que podría ser modificado por afuera. Esto se solucionaría clonando el nodo. Esta "librería" es simplemente un wrapper sobre el nodo. Cada instancia es creada para un nodo específico y no se le puede asignar otro; pero el nodo en sí es mutable.
El segundo punto se basa en el patrón Null Object: la idea es prescindir de null en el API para evitar el fatídico Null Pointer Exception. Más abajo lo vemos.
Como dije antes la librería es elemental, y sus limitaciones son:
  • No sirve para "recorrer" el XML sino para obtener elementos conocidos
  • No accede a los atributos de los elementos
No sería nada complicado superar esas limitaciones. Pero no es tanto por la utilidad de la librería que escribo este post sino porque me parece un buen ejemplo de API, las ideas son aplicables a otras cosas. Aparte también ilustra la idea de tener una capa de abstracción sobre una librería existente, cuando los casos de uso son lo suficientemente simples, y se desea que el código refleje claramente la intención sin que uno deba perderse en la complejidad (o torpeza) de la librería original.


API de XmlNode

Esta es la firma de los constructores:
   
   public XmlNode();
   public XmlNode(Node node);
   public XmlNode(Document doc);
El primero es el Null Object, y si bien es un constructor público, lo normal será que sólo se utilice desde la misma clase y no desde afuera. El segundo toma un Node y el tercero un Document. Este último toma el nodo raiz del documento. La idea es que podamos partir de un documento o un nodo cualquiera, y olvidarnos de la diferenciación: lo que tenemos es un árbol de nodos.
    
    public String getName();
    public String getValue();

Con estos métodos obtenemos el nombre (tag) y el valor (contenido) del nodo. Ambos retornarán null si es un Null Object.

    public XmlNode subNode(String tagName);

Este método en cambio nunca retorna null y permite invocaciones encadenadas. El argumento debe ser un tag de un nodo hijo (inmediatamente relacionado con el actual). Veamos un ejemplo. Si creamos un XmlNode a partir de esto:

   <a> 
      <b>
         <c>hola</c>
         <d>que tal</d>
      </b>
   </a>

Podremos accederlo así:

   String nombre = nodo.getName(); // "a"
   XmlNode nodoB = nodo.subNode("b"); // subnodo <b>
   XmlNode nodoC = nodo.subNode("b").subNode("c"); // subnodo <c>
   String valor1 = nodo.subNode("b").subNode("d").getValue(); // "que tal"
   String valor2 = nodoC.getValue(); // "hola"

Y también así:

   XmlNode nodoX = nodo.subNode("z").subNode("y").subNode("x");
   String valor3 = nodoX.getValue(); // null

Ahí vemos la invocación encadenada con nodos inexistentes. En nodoX nos quedó un Null Object. Para verificar si el XmlNode "está definido" o es nulo, tenemos también el siguiente método (inspirado en el homónimo de Option en Scala):

    public boolean isDefined();

Así será más prolijo verificar si el nodo existe, en lugar de ver si getName() o getValue() retornan null.

El código

import org.w3c.dom.Document;
import org.w3c.dom.Node;
import org.w3c.dom.NodeList;

public class XmlNode
{
    protected Node node = null;
    
    public XmlNode()
    {
    }
    
   public XmlNode(Node node)
    {
        this.node = node;
    }
    
    public XmlNode(Document doc)
    {
        this.node = doc.getDocumentElement();
    }
    
    public XmlNode subNode(String tagName)
    {
        if(node != null)
        {
            NodeList nl = node.getChildNodes();
            for(int i = 0; i < nl.getLength(); i++)
            {
                Node n = nl.item(i);
                
                if(n.getNodeName().equals(tagName))
                {
                    return new XmlNode(n);
                }
            }
        }
        return new XmlNode();
    }
    
    public String getName()
    {
        return !this.isDefined()? null : node.getNodeName();
    }
    
    public String getValue()
    {
        return !this.isDefined()? null : node.getFirstChild().getNodeValue();
    }
    
    public boolean isDefined()
    {
        return this.node != null;
    }
}

sábado, 4 de abril de 2009

Una vuelta de tuerca más a la generación del diagrama

En el post anterior vimos cómo generar un diagrama Nassi-Schneiderman con tablas HTML. Hicimos un generador abstracto que nos permitiría hacer implementaciones alternativas, es decir, el diseño es modularizable.

trait Generator[T] {
  def nullResult:T
  def generate(o:Option[Node]):T = o match {
    case Some(x) => generate(x)
    case _ => nullResult
  }
  def generate(n:Node):T
}

En nuestro generador de HTML, el parámetro de tipo fue String, naturalmente, ya que generamos HTML con Strings. ¿Habrá sido una exageración parametrizar ese tipo? ¿Se les ocurre un generador que use un tipo diferente a String? 

¿Y por qué no generar el diagrama como imagen? Un poco de AWT no hace mal. Mi nueva implementación usa java.awt.Image. Así es como se ve el nuevo diagrama (a partir del mismo código usado como entrada en el post anterior):


Creo que no hace falta explicar nada, el diagrama habla por sí mismo... sólo acotar que, en los IF que no tienen sección ELSE, en vez de dividir el cuadro por la mitad, hice un 90%/10% para evitar que se ocupe mucho espacio con la parte vacía. Faltan algunas mejoras, como incluir el nombre del módulo, los parámetros y la sección de declaraciones; y parametrizar el ancho de la imagen, que ahora está hardcodeado. En cuanto al alto, debería poder ser calculado según el largo del código, pero no lo resolví y por ahora también está hardcodeado. Definí las siguientes clases auxiliares inmutables, porque esto tiene uso intensivo de "puntos" y "áreas":

case class Point(x:Int, y:Int)

case class Area(start:Point, end:Point) {
  lazy val width = end.x - start.x
  lazy val height = end.y - start.y
  lazy val middleX:Int = start.x + (width / 2) 
  lazy val middleTop = Point(middleX, start.y)
  lazy val middleBottom = Point(middleX, end.y)
  lazy val leftBottom = Point(start.x, end.y)
  lazy val leftTop = start
  lazy val rightTop = Point(end.x, start.y)
}

Los valores definidos en Area son útiles para que el código sea más claro. Si fueran funciones, el código se ejecutaría en cada invocación. Al ser val, el código se ejecuta a lo sumo una vez: el valor queda "recordado" para subsiguientes referencias. Y son lazy para que no se ejecuten hasta ser referenciados.

case object Area {
  def apply(a1:Area, a2:Area):Area = 
      Area(Point(a1.start.x min a2.start.x, a1.start.y min a2.start.y),
           Point(a1.end.x max a2.end.x, a1.end.y max a2.end.y))
}

Con esto logramos que Area pueda ser usado como función, pasando dos áreas como argumentos. El resultado será un área que abarque completamente a esas dos. Esto fue necesario para, luego de procesar ambas secciones de un IF, obtener el área completa de la estructura (ya que cada sección tiene una altura independiente, según el código contenido). Finalmente, el generador:

trait ImageGenerator extends Generator[Image] {
  def imageWidth:Int
  val totalWidth = imageWidth
  val imageHeight = 800
  def nullResult = null

  def generate(n:Node):Image = {
    val img = new BufferedImage(imageWidth, imageHeight, BufferedImage.TYPE_BYTE_BINARY)
    val g = img.createGraphics
    g.setPaint(Color.WHITE)
    g.fillRect(0, 0, imageWidth, imageHeight)
    g.setPaint(Color.BLACK)
    (new GraphicsImageGenerator(g)).generate(n, totalWidth - 20, Point(10,20))
    img
  }
}

El método abstracto imageWidth deberá ser implementado por quien use este trait, para indicar el ancho de imagen deseado. La altura en cambio, viene horriblemente hardcodeada de fábrica, por ahora. Obviamente esto no es todo, el trabajo sucio lo hace otra clase, a la que llamé GraphicsImageGenerator. El método generate crea la Image que vamos a retornar. Inicializa el correspondiente objeto Graphics y se lo pasa a una nueva instancia de GraphicsImageGenerator. Ésta también define un método generate pero requiere argumentos adicionales: aparte del Node, necesita saber con qué ancho cuenta para dibujarlo, y a partir de qué punto. Estos valores se calcularán para cada nodo a dibujar, aquí sólo se envían los valores iniciales que corresponden al nodo raíz del AST. 

Y ahora sí, les dejo esa clase para que escudriñen si tienen ganas.

class GraphicsImageGenerator(val g:Graphics2D)
{
  val lineHeight = 11
  val stmtSep = 3
  val stmtHeight = 15
  val loopThickness = 15

  private def wrap(s:String, w:Int) = (new LineBreaker(s, w, g.getFontMetrics)).getSubtrings
  private def widthOf(ss:List[String]) = ((ss map g.getFontMetrics.stringWidth) :\ 0)(_ max _)
  private def drawRect(a:Area) = g.drawRect(a.start.x, a.start.y, a.end.x - a.start.x, a.end.y - a.start.y)
  private def drawLine(p1:Point, p2:Point) = g.drawLine(p1.x, p1.y, p2.x, p2.y)
  
  private def drawJustified(text:String, w:Int, p:Point, drawRect:Boolean)(fx:(Int, Int, Int) => Int) : Area = {
    val substrings = wrap(text, w)
    var y = p.y + stmtHeight
    substrings foreach { s =>
      g.drawString( s, fx(p.x, g.getFontMetrics.stringWidth(s), w), y)
      y += lineHeight
    }
    Area(p, Point(p.x + w, y))
  }
  private def drawLeftJustified(text:String, w:Int, p:Point) = drawJustified(text, w, p, false) {
    (x:Int, textWidth:Int, w:Int) => x
  } 
  private def drawRightJustified(text:String, w:Int, p:Point) = drawJustified(text, w, p, false) {
    (x:Int, textWidth:Int, w:Int) => (x + w) - textWidth
  } 
  private def drawCentered(text:String, w:Int, p:Point) = drawJustified(text, w, p, true) {
    (x:Int, textWidth:Int, w:Int) => (x + (w / 2)) - (textWidth / 2)
  } 
  
  def generate(n:Node, w:Int, p:Point):Point =
    n match {
      case stmt:Stmt => 
            drawLeftJustified(stmt.s, w, p).leftBottom
      case loop:Loop => 
            val areaLoop = drawLeftJustified(loop.head, w, p)
            val startCode = Point(p.x + loopThickness + 2, areaLoop.end.y + 2)
            val loopBodyBottom = generateCode(loop.body, (w - 4) - loopThickness, startCode)
            val endPoint = Point(areaLoop.end.x, loopBodyBottom.y)
            drawRect(Area(startCode, endPoint))
            drawRect(Area(areaLoop.leftTop, endPoint))
            Point(p.x, endPoint.y)
      case cond:Cond => 
            val areaCond = drawCentered(cond.c, w, p)
            drawRect(areaCond)
            val sepStart = if(cond.cElse.isEmpty) Point(p.x + (w * .9).asInstanceOf[Int], areaCond.end.y) else areaCond.middleBottom
            val thenWidth = if(cond.cElse.isEmpty) (w * .9).asInstanceOf[Int] - 4 else (w/2) - 4 
            drawLine(areaCond.leftTop, sepStart)
            drawLine(areaCond.rightTop, sepStart)
            val pointThen = generateCode(cond.cThen, thenWidth, Point(p.x + 2, areaCond.end.y + 2))
            val pointElse = generateCode(cond.cElse, (w/2) - 4, Point(p.x + 2 + (w/2), areaCond.end.y + 2))
            val areaCode = Area(areaCond.leftBottom, Point(areaCond.end.x, pointThen.y max pointElse.y))
            drawRect(areaCode)
            drawLine(sepStart, Point(sepStart.x, areaCode.end.y))
            areaCode.leftBottom
      case block:Block => 
            val codeEndPoint = generateCode(block.content, w - 4, Point(p.x + 2, p.y + 2))
            val endPoint = block.exceps match {
              case None => codeEndPoint
              case Some(es) => generate(es, w - 4, codeEndPoint)
            }
            drawRect(Area(p, Point(p.x + w, endPoint.y)))
            endPoint
      case excepSection:ExcepSection =>
            generateCode(excepSection.ee, w, p)
      case whenExcep:WhenExcep =>
            val areaWhen = drawLeftJustified(whenExcep.e, w - loopThickness, Point(p.x + loopThickness, p.y))
            val endPoint = generateCode(whenExcep.body, w, Point(p.x, areaWhen.end.y))
            drawLine(p, Point(p.x + w, p.y))
            drawLine(Point(p.x + loopThickness, p.y), Point(p.x, p.y + loopThickness))
            drawLine(Point((p.x + w) - loopThickness, p.y), Point(p.x + w, p.y + loopThickness))
            endPoint
      case module:Module => generate(module.body, w, p)
      case _ => p
    }    

  private def generateCode(codeList:List[Node], w:Int, p:Point):Point =
    (p /: codeList) { (start:Point, c:Node) => generate(c, w, start) }
}

Nota: no incluyo la clase LineBreaker, que sirve para cortar un String en varios según sea necesario para que el texto entre en un ancho gráfico determinado.

jueves, 2 de abril de 2009

Parseando en Scala (6): Generando la salida

Nuestro propósito era parsear código PL/SQL, cosa que ya vimos en los posts anteriores, y generar como salida un diagrama estructurado. 

Vamos a usar el siguiente código PL/SQL para probar el experimento. No importa lo que hace, es cualquier cosa que se me ocurrió.

PROCEDURE MYPROC (Param IN NUMBER) IS
 AUXVAR VARCHAR2(10) := NULL;
begin
 IF Param = 1 THEN
  AUXVAR = 'A';
 ELSIF Param = 2 THEN
  AUXVAR = 'B';
 END IF;

 if AUXVAR IS NOT NULL
 THEN
  FOR RECORD IN (SELECT * FROM MYTABLE WHERE FLD = AUXVAR)
  LOOP
   IF RECORD.EXPIRY <= SYSDATE 
   THEN
    LOG_EXPIRED(RECORD.ID);
   END IF; 
  END LOOP;   
 END IF;      
 
 dbms_output.put_line('END OF MYPROC WITH PARAM = ' || Param); 
 
 exception  
 when others then 
  dbms_output.put_line('OOPS!'); 
end; 

Y vemos antes que nada el resultado que obtuve, tal como lo veo en el navegador. Como decíamos, es una versión HTML del diagrama Nassi-Schneidermann donde tenemos una representación visual de la estructura lógica. 


Cada IF es un recuadro, con un encabezado que indica la condición (seguida de un signo de pregunta), y se divide en dos secciones: por convención, la izquierda corresponde a verdadero y la derecha a falso (THEN y ELSE respectivamente). Se puede ver cómo los IF encadenados con ELSIF quedaron resueltos como IFs anidados. Los ELSE vacíos también se dibujan, con "---". Los ciclos, como el FOR del ejemplo, son recuadros que muestran a la izquierda y en verde la cláusula correspondiente, y a la derecha el código. La sección EXCEPTION se muestra al final del recuadro del bloque debajo de una línea punteada. 

Esto es generado por un módulo a partir del AST  obtenido por el parseador. Pero el generador de HTML no tiene por qué ser la única opción de generación del diagrama, de hecho ya tengo un generador alternativo que comentaré más adelante. El punto es que para permitir la modularización, armamos una jerarquía de traits. El siguiente trait es el padre de los generadores.

trait Generator[T] {
 def nullResult:T
 def generate(o:Option[Node]):T = o match {
  case Some(x) => generate(x)
  case _ => nullResult
 }
 def generate(n:Node):T
}

Si recordamos, Node es el supertipo del modelo  que estamos usando. El parámetro de tipo, T, es necesario porque para las posibles salidas pueden usarse diferentes tipos; de hecho esto es resultado de refactorizar mi código para permitir el generador alternativo en forma elegante. Con el método abstracto generate, requerimos que todos los generadores implementen la "transformación" de un Node cualquiera (de todos los posibles según el modelo), en algo de tipo T. Para la generación HTML ese tipo será String. Agregué una implementación default de generate que, en vez de tomar un Node toma un Option[Node]. Si se trata de un nodo definido, se deriva el control al método abstracto recién mencionado, y si no, a otro que define cómo se representa algo "vacío" para el tipo T. Esto me pareció práctico porque el modelo suele tener relaciones con opcionalidad: así puedo invocar indistintamente la generación de un nodo concreto o de un nodo que puede estar presente o no. Finalmente, el generador que hace todo el trabajo:

trait HTMLGenerator extends Generator[String] {
  def nullResult = ""
  def generate(n:Node):String = n match {
    case Stmt(s) => s.replace("<","&lt;") + "<br>\n"
    
    case WhenExcep(e,body) => "<p>when " + e + " then<br>\n" + 
      (body map generate).mkString + "</p>\n"
    
    case ExcepSection(s) => openCell("class=\"excsec\"") + 
      "<strong>exception</strong><br>\n" + 
      (for(w <- s) yield generate(w)).mkString +
      closeCell
    
    case Block(stmts, exceps) => "<table>" +
      openCell +
      (stmts map generate).mkString + 
      closeCell +
      (if(exceps.isDefined) generate(exceps.get) else "") +
      "</table><br>\n"
    
    case Loop(h,body) => "<table><tr><td class=\"loop\">" +
      h +
      "</td>\n<td>" +
      (body map generate).mkString +
      "</td></tr></table>\n"     
      
    case Cond(c,ct,ce) => "<table>" +
        openCell("colspan=\"2\" class=\"ifhead\"") + 
        c + 
        "<big><b> ?</b></big>" +
        closeCell + 
        openCell("class=\"ifthen\"") + 
        (ct map generate).mkString + 
        "</td><td class=\"ifelse\">" + 
        (ce match {
          case Nil => "---"
          case xs => (xs map generate).mkString 
        }) + 
        closeCell +
        "</table><br>\n"
    
    case Module(t,n,p,r,v,b) => startHtml + "<h3>" + t + " " + n + "</h3>\n" +
        (p match { case Some(x) => generate(x); case None => "" }) + "<br>\n" +
        (if(v != Nil) "<table>" + openCell + (v map generate).mkString + closeCell + "</table>" else "") +
        "<hr><br>" + generate(b) + endHtml
  }

  private val startHtml = "<html><head><style type=\"text/css\">\n" +
     "table { width: 100%; border: solid thin }\n" +
     ".comment { color: darkgreen; font-style: italic }\n" +
     ".ifhead { background-color: moccasin; text-align: center }\n" +
     ".ifthen { border-top: solid thin; border-right: solid thin; }\n" +
     ".ifelse { border-top: solid thin; border-left: solid thin; }\n" +
     ".excsec { border-top: dashed thin; }\n" +
     ".loop { border-right: solid thin; background-color: MediumAquamarine; }\n" +
     "</style></head><body>\n"
  
  private def openCell(modif:String) = "<tr><td " + modif + ">"
  private def openCell:String = openCell("")
  private val closeCell = "</td></tr>"  
 
  private val endHtml = "</body></html>"
}

Definimos nullResult, para los nodos opcionales que no estén presentes, como un String vacío. Implementamos generate haciendo pattern matching sobre el nodo recibido. Contemplamos todos los tipos de nuestro modelo y generamos la representación HTML deseada para cada uno. Los detalles de la implementación puede que no sean del todo claros a primera vista, pero la idea sí, es bien simple. 

El nodo Module siempre estará en la raiz del AST, por eso es el encargado de especificar el comienzo y el final del documento HTML. Entre una cosa y la otra, se producirán todas las invocaciones recursivas de generate para los nodos contenidos en el árbol. Los estilos CSS acá están hardcodeados, pero idealmente serían customizables. 

Con esto finalizamos la serie, aunque me parece que habrá un bonus.