Creación y uso de Javadoc con Netbeans

Javadoc es un paquete de desarrollo de java que nos genera documentación sobre nuestro proyecto de cada una de nuestras clases en una jerarquía de árbol.

Su uso es recomendable para todo proyecto, incluido los proyectos pequeños porque nos ayuda a tener siempre un código bien documentado, el único contra que tiene su uso, es que es muy tedioso documentar cada paso que se da al escribir el código (en general por los programadores flojos como yo), por lo demás, es una buena regla de programación.

Javadoc funciona por medio de MARCAS que le ayudan al API reconocer las partes que queremos  documentar y crear los archivos HTML.

@author - El nombre del autor del proyecto por ejemplo pepito :)
@version - La versión del proyecto
@see - Añade una referencia a una clase, método o enlace web
@param - Nombre de parámetro utilizado en un método incluido su significado
@return - El resultado de un método incluido su descripción
@exception - Nombre de la excepción mas una descripción
@throws - Nombre de la excepción mas una descripción
@deprecated - Añade una alerta al usuario de que el método que sigue a continuación ya no debe usarse y que será eliminado en versiones posteriores.


Al escribir los comentarios también podemos hacer uso de algunas etiquetas HTML para decorar un poco más nuestra documentación.


Para indicarle a Javadoc que queremos incluir documentación, debemos comenzar los comentarios de la siguiente manera:

/**
* Esto para Javadoc
*/

Veamos su uso con un ejemplo.


Creamos una clase llamada "Clase_java" y en el encabezado colocamos el autor de la clase, la instrucción @see con un enlace a una página web, también podemos agregar la versión de la clase:

/**
 * @author Mouse
 * @see <a href="http://www.jc-mouse.net">http://www.jc-mouse.net</a>
 * @version 1.2 07 de Mayo de 2013
 */
public class Clase_Java {
...
}

También podemos documentar las variables que hacen parte de nuestro código

/**
 * Variable privada: Nombre del autor
 */
private final String Autor = "jc Mouse";

/**
 * Variable publica: Una frase para reflexionar
 */
public String Frase_del_dia = "Carpe diem";

Cuando se haga uso de estas variables comentadas, en el editor de Netbeans podremos ver algo como esto:

No debemos olvidar tambien comentar e constructor de clase

/**
 * Constructor de clase     
 */
public Clase_Java(){
...
}

Cuando creamos un método es recomendable documentar los parámetros de entrada, si es que los tuviera, y si este método retorna algún resultado, utilizar la marca @return, si por el contrario el método es de la forma VOID, no se usa nada. Así también para las excepciones que puedan ocurrir se usa @exception. En la descripción del método, se puede incluir un ejemplo de uso encerrado en las etiquetas PRE, por ejemplo:

    /**
     * Método que convierte una cadena de la forma "yyyy-MM-dd HH:mm" a Date
     * <PRE> Clase_Java cj = new Clase_Java();
     * Date date = cj.StringToDate("2012-10-01 12:00")</PRE>
     * @param value String que debe tener la forma "yyyy-MM-dd HH:mm"
     * @return Date Un objeto Date con la fecha parseada
     * @exception ParseException Error de parseo, ocurre cuando no se puede convertir un String a Date          
     * @since incluido desde la version 1.0
     */
    public Date StringToDate( String value )
    {
        Date date = new Date();
        SimpleDateFormat formatter = new SimpleDateFormat("yyyy-MM-dd HH:mm");
         try {
            date = (java.util.Date) formatter.parse( value );
        } catch (ParseException ex) {
            System.err.println( ex.getMessage() );
        }
        return date;
    }

Cuando utilicemos este método, podremos ver que Netbeans nos despliega toda la información en cuando se hace referencia al nombre StringToDate.

Cuando tenemos varias versiones de un proyecto y vamos actualizando los metodos, antes de eliminar los métodos que ya no se harán uso, es preferible, primero alertar al usuario que ciertas funciones dejaran de existir en versiones posteriores, para esto, en la descripción se añade la marca @deprecated, y la marca @see, que hace referencia a la función de reemplazo, es decir, supongamos que en una primera versión tenemos un método llamado Suma pero que en una nueva versión se decide crear una nueva versión suma_enteros, entonces lo que debemos hacer es añadir en la documentación de Suma, la alerta de que esta función ya no se utilizara más y que es mejor usar la nueva función suma_enteros, es decir:

/**
     * Metodo que suma dos enteros y retorna el resultado, gran cosa no :)
     * @param a Número Entero
     * @param b Número Entero
     * @return int Un entero que es el resultado de a + b
     * @deprecated No se aconseja su uso
     * @see suma_enteros( int, int )
     */
    public int Suma( int a , int b)
    {
        return a + b;
    }

    /**
     * Metodo que suma dos enteros positivos y retorna el resultado
     * @param a Número Entero
     * @param b Número Entero
     * @return int Un entero que es el resultado de a + b, si los numeros son negativos, retorna cero.
     */
    public int suma_enteros( int a, int b)
    {
        int resultado = 0;
        if( a>0 && b>0)
            resultado = a + b;
        return resultado;
    }

Ahora, cuando se haga uso del método Suma, este nos aparecerá con un subrayado y con la alerta correspondiente:

El código completo de la clase es:

package jcdoc;
import java.text.ParseException;
import java.text.SimpleDateFormat;
import java.util.Date;
/**
 * @author Mouse
 * @see <a href="http://www.jc-mouse.net">http://www.jc-mouse.net</a>
 * @version 1.2 07 de Mayo de 2013
 */
public class Clase_Java {

    /**
     * Variable privada: Nombre del autor
     */
    private final String Autor = "jc Mouse";
    /**
     * Variable publica: Una frase para reflexionar
     */
    public String Frase_del_dia = "Carpe diem";
    
    /**
     * Constructor de clase     
     */
    public Clase_Java(){
        System.out.println( this.Autor + " te aconseja '" + this.Frase_del_dia + "'" );              
    }

    /**
     * Método que convierte una cadena de la forma "yyyy-MM-dd HH:mm" a Date
     * <PRE> Clase_Java cj = new Clase_Java();
     * Date date = cj.StringToDate("2012-10-01 12:00")</PRE>
     * @param value String que debe tener la forma "yyyy-MM-dd HH:mm"
     * @return Date Un objeto Date con la fecha parseada
     * @exception ParseException Error de parseo, ocurre cuando no se puede convertir un String a Date          
     * @since incluido desde la version 1.0
     */
    public Date StringToDate( String value )
    {
        Date date = new Date();
        SimpleDateFormat formatter = new SimpleDateFormat("yyyy-MM-dd HH:mm");
         try {
            date = (java.util.Date) formatter.parse( value );
        } catch (ParseException ex) {
            System.err.println( ex.getMessage() );
        }
        return date;
    }

    /**
     * Metodo que suma dos enteros y retorna el resultado, gran cosa no :)
     * @param a Número Entero
     * @param b Número Entero
     * @return int Un entero que es el resultado de a + b
     * @deprecated No se aconseja su uso
     * @see suma_enteros( int, int )
     */
    public int Suma( int a , int b)
    {
        return a + b;
    }

    /**
     * Metodo que suma dos enteros positivos y retorna el resultado
     * @param a Número Entero
     * @param b Número Entero
     * @return int Un entero que es el resultado de a + b, si los numeros son negativos, retorna cero.
     */
    public int suma_enteros( int a, int b)
    {
        int resultado = 0;
        if( a>0 && b>0)
            resultado = a + b;
        return resultado;
    }

}

Para generar los HTML, vamos a Ejecutar -> Generar JavaDoc. y esperamos unos segundos a que nos genere todos los archivos.

Eso es todo :), bajate el proyecto utilizado en este tutorial AQUI

continue reading

Lectura y escritura de imagenes JPG en PostgreSQL

En este tutorial veremos una forma para registrar archivos JPG en una base de datos PostgreSQL y recuperarlos para utilizarlos en controles Swing. Como vimos en un tutorial anterior a este donde utilizamos una base de datos MySQL, el procedimiento es prácticamente el mismo, claro con pequeñas diferencias.

Cuando se desea almacenar fisicamente el contenido de una imagen en una base de datos, este debe ser convertido a una cadena de bytes, para esto el campo donde se guardara la imagen debe ser del tipo BOOL en MySQL y para Postgres tenemos el tipo BYTEA, de esta manera podemos almacenar el contenido de un archivo JPG en la base de datos, ahora para recuperar el contenido de esta imagen y utilizarlo en nuestra aplicación, debemos procesar la cadena de bytes y convertirlo nuevamente en una imagen con la cual podamos trabajar.

Ver tutorial

continue reading

Crea tu lector Feed con Java

En este tutorial se crea paso a paso un lector Feed utilizando el lenguaje Java y el IDE Netbeans, ademas se hace uso de la librería rome-1.0 y JDom, el lector es sencillo pero cuenta con una interfaz gráfica lo que hace de este proyecto bastante entretenido. Ve el video y enterate un poco más de lo que haremos en este tutorial.

"Una fuente web o canal web (en inglés web feed) es un medio de redifusión de contenido web. Se utiliza para suministrar información actualizada frecuentemente a sus suscriptores. En su jerga, cuando una página web "redifunde" su contenido mediante una fuente web, los internautas pueden "suscribirse" a ella para estar informados de sus novedades. Los interesados pueden usar un programa "agregador" para acceder a sus fuentes suscritas desde un mismo lugar.


Son muy utilizados en los blogs o bitácoras de Internet, así como en prensa electrónica. Cada día hay más medios que utilizan este sistema de redifusión web. La gran difusión de este tipo de servicio web ha estimulado el interés en otros sectores que comienzan a ver en las fuentes web una forma efectiva de difundir y compartir información empresarial."

Ver tutorial

continue reading

Cargar datos a un JTree desde una base de datos

Problema: Se necesita cargar los datos de una base de datos hacia un JTree, la base de datos es de un país que tiene departamentos y los departamentos tienen provincias y las provincias, municipios, al hacer clic en un nodo, debe desplegar sus nodos hijos. Al realizar clic en un nodo, se debe desarrollar una acción.

Base de datos:

-- 
-- Base de datos: 'dbbolivia'
-- 
-- 
-- Estructura de tabla para la tabla 'departamento'
-- 
CREATE TABLE departamento (
  dep_id int(2) NOT NULL,
  dep_nombre varchar(32) NOT NULL,
  PRIMARY KEY  (dep_id)
);
-- 
-- Estructura de tabla para la tabla 'provincia'
-- 
CREATE TABLE provincia (
  prov_id int(2) NOT NULL auto_increment,
  prov_nombre varchar(32) NOT NULL,
  dep_id varchar(32) NOT NULL,
  PRIMARY KEY  (prov_id)
);
-- 
-- Estructura de tabla para la tabla 'municipio'
-- 
CREATE TABLE municipio (
  mun_id int(2) NOT NULL auto_increment,
  mun_nombre varchar(32) NOT NULL,
  prov_id int(2) NOT NULL,
  PRIMARY KEY  (mun_id)
);

Solución.
¿Qué necesitamos?

• Netbeans
• Servidor MySQL

Crear la base de datos y agregar algunos datos

1. Crear una proyecto netbeans, agregar un JFrame (interfaz.java) y agregar los siguientes controles:

2. Agregar también una clase (nombre:database.java) para inter actuar con la base de datos MySQL. el código de la clase es:

import java.sql.*;
/**
 * @web http://www.jc-mouse.net
 * @author Mouse
 */
public class database {
  /* DATOS PARA LA CONEXION */
  private String bd = "dbbolivia";
  private String login = "";//USUARIO
  private String password = "";//CONTRASEÑA
  private String url = "jdbc:mysql://localhost/"+bd;
  private Connection conn = null;
//___________________________________________________________________________________ Soy una barra separadora :)
   public database(){
      try{
         //obtenemos el driver de para mysql
         Class.forName("com.mysql.jdbc.Driver");
         //obtenemos la conexión
         conn = DriverManager.getConnection(url,login,password);
         if (conn!=null){
            System.out.println("OK base de datos "+bd+" listo");
         }
      }catch(SQLException e){
         System.out.println(e);
      }catch(ClassNotFoundException e){
         System.out.println(e);
      }
    }
//___________________________________________________________________________________ Soy una barra separadora :)
    public Connection getConnection()
    {
        return this.conn;
    }
//___________________________________________________________________________________ Soy una barra separadora :)
/* METODO PARA REALIZAR UNA CONSULTA A LA BASE DE DATOS
 * INPUT:
 *      table => nombre de la tabla donde se realizara la consulta, puede utilizarse tambien INNER JOIN
 *      fields => String con los nombres de los campos a devolver Ej.: campo1,campo2campo_n
 *      where => condicion para la consulta
 * OUTPUT: un object[][] con los datos resultantes, sino retorna NULL
 */
    public Object [][] select(String table, String fields, String where){
      int registros = 0;
      String colname[] = fields.split(",");

      //Consultas SQL
      String q ="SELECT " + fields + " FROM " + table;
      String q2 = "SELECT count(*) as total FROM " + table;
      if(where!=null)
      {
          q+= " WHERE " + where;
          q2+= " WHERE " + where;
      }
      //obtenemos la cantidad de registros existentes en la tabla
      try{
         PreparedStatement pstm = conn.prepareStatement(q2);
         ResultSet res = pstm.executeQuery();
         res.next();
         registros = res.getInt("total");
         res.close();
      }catch(SQLException e){
         System.out.println(e);
      }
    //se crea una matriz con tantas filas y columnas que necesite
    Object[][] data = new String[registros][fields.split(",").length];
    //realizamos la consulta sql y llenamos los datos en la matriz "Object"
      try{
         PreparedStatement pstm = conn.prepareStatement(q);
         ResultSet res = pstm.executeQuery();
         int i = 0;
         while(res.next()){
            for(int j=0; j<=fields.split(",").length-1;j++){
                data[i][j] = res.getString( colname[j].trim() );
            }
            i++;         }
         res.close();
          }catch(SQLException e){
         System.out.println(e);
    }
    return data;
 }
//___________________________________________________________________________________ Soy una barra separadora :)
}

Esta clase se conecta a la base de datos, también cuenta con una clase para realizar una consulta
3. Clase interfaz.java
- Las librerias que se utilizan son:

import javax.swing.event.TreeSelectionEvent;
import javax.swing.event.TreeSelectionListener;
import javax.swing.tree.DefaultMutableTreeNode;
import javax.swing.tree.DefaultTreeModel;
import javax.swing.tree.TreePath;

- Crear una instancia a la clase database.java:

private database db = new database();

- Implementar la clase database, así como el código para llenar el JTree en el constructor de la clase interfaz.java:

public interfaz() {
        initComponents();
        this.setTitle("JTree - http://www.jc-mouse.net/");

     //se crea la raiz
     DefaultMutableTreeNode pais = new DefaultMutableTreeNode("Bolivia");
     DefaultMutableTreeNode departamento;
     DefaultMutableTreeNode provincia;
     DefaultMutableTreeNode municipio;     

     //se obtienen los departamentos
     Object[][] data_dep =  db.select("departamento", " dep_id, dep_nombre", null);
     if( data_dep.length > 0)
     {
        for(int i=0; i < data_dep.length; i++)
        {
            //se crea hojas departamentos
            departamento = new DefaultMutableTreeNode(data_dep[i][1]);
            pais.add(departamento);
            //se obtiene las provincias
            Object[][] data_prov =  db.select("provincia", "prov_id,prov_nombre" , " dep_id='" + data_dep[i][0].toString()+"' ");
            if( data_prov.length > 0)
            {
                for(int j=0; j< data_prov.length; j++)
                {
                    provincia = new DefaultMutableTreeNode(data_prov[j][1]);
                    departamento.add(provincia);
                    //se obtienen los municipios
                    Object[][] data_mun =  db.select("municipio", "mun_id,mun_nombre" , " prov_id='" + data_dep[j][0].toString()+"' ");
                    if( data_mun.length > 0)
                    {
                        for(int k=0; k< data_mun.length; k++)
                        {
                            municipio = new DefaultMutableTreeNode(data_mun[k][1]);
                            provincia.add(municipio);
                        }
                    }
                }
            }
        }
     }

    
    DefaultTreeModel modelo = new DefaultTreeModel(pais);
    this.jTree1.setModel(modelo);

    jTree1.getSelectionModel().addTreeSelectionListener(new TreeSelectionListener() {

        public void valueChanged(TreeSelectionEvent e) {
            // Se obtiene el Path seleccionado
            TreePath path = e.getPath();
     Object [] nodos = path.getPath();
            String txt= jTextArea1.getText() + "Path seleccionado: ";
            for (Object nodo: nodos)
                txt+=nodo.toString() + " | ";                
            txt+="\n";            
     // Se obtiene el Nodo seleccionado
            DefaultMutableTreeNode NodoSeleccionado = (DefaultMutableTreeNode)nodos[nodos.length-1];            
            txt+="-> Accion para Nodo Seleccionado [" + NodoSeleccionado.getUserObject().toString() + "]";
            txt+="\n";
     jTextArea1.setText(txt);
  }            
    });

    }

- Explicación: Se crea la raíz país (Bolivia), después se extrae los registros de la tabla departamentos y se añade a la raíz país, se extrae los registros provincias y se añade a su raíz departamento, se repite el proceso para municipios.

- Ejecutar

Descargar proyecto HERE

continue reading

Florence Colgate el rostro perfecto

La belleza es un concepto abstracto y evidentemente relativo. Su existencia está ligada a una percepción que a su vez está determinada, en buena medida, por preceptos culturales y asociaciones específicas. Sin embargo, como suele ocurrir con la mirada científica, también se han establecido parámetros que delinean la composición perfecta de la belleza en referencia al rostro humano.

[Dimask - Jugar]

Si es cierto que la belleza se puede medir en función de la simetría facial, Florence Colgate es probablemente una de las mujeres más bellas del mundo.

Concederle el primer puesto que le otorgan algunos titulares me resulta exagerado teniendo en cuenta que no se han valorado a todas las mujeres de la Tierra, pero matices a parte lo cierto es que esta estudiante británica de 18 años acaba de ganar el concurso Lorraine Naked del canal ITV al que optaron más de 8000 candidatas sin ningún retoque quirúrgico, que tampoco usaron maquillaje.

Y de acuerdo con las proporciones postuladas como idóneas por la ciencia, la británica Florence Colgate es la mujer más hermosa del planeta. La distancia entre sus orejas es exactamente el doble del trecho que separa a una de sus pupilas de la otra. Además, la distancia que hay de sus ojos a su boca equivale a una tercera parte de la que separa su barbilla de la línea donde comienza su cabello, arriba de la frente. Ambas proporciones coinciden con la belleza perfecta que los científicos obtuvieron tras correlacionar múltiples variables.

Pues bueno, bonita si es, a mi me gusta su mirada más que otra cosa pero de ahí a que sea perfecto pues depende de cada quien digo yo, si quieres averiguar que tan perfecto es tu rostro prueba Dimask, y compruébalo por ti mismo, No Apto Para Acomplejados :)

Ahora también existe una herramienta on-line para comprobar si tu rostro es simétrico

Visitar página Dimask

continue reading

Captura de pantalla Java/Robot

Este es un pequeño proyecto de un capturador de pantalla escrito en lenguaje java con la ayuda del IDE de Netbeans version 6.9, utilizando la clase Robot de java.

La clase que hace todo el trabajo (de la captura) es la clase capture.java, el código de esta clase es:

package jcapture;
import java.awt.*;
import java.awt.image.*;
import java.io.*;
import javax.imageio.ImageIO;
import javax.swing.JFileChooser;
import javax.swing.JOptionPane;
import javax.swing.filechooser.FileNameExtensionFilter;
/**
 * @web http://www.jc-mouse.net
 * @author Mouse
 */
public class Capture {    
   
   private BufferedImage image;   
   private FileNameExtensionFilter filter = new FileNameExtensionFilter("Archivo de Imagen","jpg");
   private JFileChooser fileChooser = new JFileChooser();

   /* CAPTURA LA PANTALLA */
   public void captureScreen(Point p , Dimension screenSize)  {
        try {
            //crea el area de captura
            Rectangle screenRectangle = new Rectangle(p, screenSize);
            Robot robot = new Robot();
            image = robot.createScreenCapture(screenRectangle);            
            Guardar_Foto();
        } catch (Exception ex) {
        }
    }

    private void Guardar_Foto(){
       String file=null;
       fileChooser = new JFileChooser();
       fileChooser.setFileFilter(filter);
       //fileChooser.setCurrentDirectory(new java.io.File("e:/capturas/"));
       int result = fileChooser.showSaveDialog(null);
       if ( result == JFileChooser.APPROVE_OPTION ){
                file = fileChooser.getSelectedFile().toString();
                guardar_imagen(file + ".jpg");
        }
    }

  /* guarda la imagen en disco*/
    private void guardar_imagen(String f){
        try {            
            //se escribe en disco en formato JPG
            ImageIO.write(image, "jpg", new File(f));
            JOptionPane.showMessageDialog(null, "Captura guardada en disco");
 } catch (IOException e) {
            JOptionPane.showMessageDialog(null, "Error: no se pudo guardar la imagen");
 }
   }

}

Un poco de explicación sobre esta clase, cuenta con el método captureScreen el cual recibe dos parámetros de entrada, un Point (origen X,Y)  y Dimension (ancho, alto) que forman un rectangulo imaginario que sirve como parametro para tomar la captura de pantalla, a su vez este metodo hace uso del metodo privado Guardar_Foto(), este método te mostrara una ventana de diálogo "Guardar como..." para que indiques el lugar y el nombre del archivo a guardar y ya para terminar el método "guardar_imagen" que creo que no hace falta indicar para que sirve :)

Bueno, todo esto lo puedes ver en el siguiente video, así queda más claro:

Descargate el proyecto desde el siguiente enlace (jCapture)

continue reading

Proyecto Prestamos con Tojorí

Proyecto java de de base de datos "Prestamos" con MySQL programado en Netbeans 6.9 utilizando la libreria "Tojorí 0.2.8"

El proyecto consta de las siguientes interfaz

Para la creación de este proyecto se hizo uso de las siguientes librerias:

• MySQL Driver JDBC - "mysql-connector-java" Libreria necesaria para la conexion a la base de datos
• JCDesktopPane - Contenedor utilizado para crea interfaz multidocumento con imagen de fondo
• J2Button - JButton con imagenes y multilínea
• Tojori-0.2.8 - Libreria para creación de base de datos

Para que el proyecto pueda ser ejecutado se deben agregar esas librerias a Netbeans.

Descargate el proyecto "DBPrestamos" completo junto a sus instrucciones de instalación

continue reading

Tojorí - Crear app de bd java/netbeans facilmente

Esta librería llamada "Tojorí" (bebida boliviana hecha a base de maiz) te ayuda a crear aplicaciones de base de datos java con MySQL utilizando el IDE de Netbeans todo desde el editor visual del mismo, muy similar a las herramientas de diseño que cuenta Delphi para interactuar con las bases de datos.

Tojorí cuenta con varios controles swing para la creación de interfaces de usuario:

• DBComboBox: swing para mostrar registros.
• DBConnection: componente para conectarse con la base de datos.
• DBDateChooser: control parecido a JCalendar, más sencillo, pero igual de eficaz.
• DBNavigator: Es una barra de controles que permite realizar las operaciones de insert, update, delete hacia la base de datos.
• DBTable: control swing para mostrar registros.
• DBTextArea: Swing para agregar textos largos 
• DBTextField: Caja de texto

Puedes ver como funciona en los siguientes videos:

Primera Parte

Segunda Parte

Puedes encontrar mayor información en este post:

Libreria Tojorí Java/MySQL

continue reading