48
1 Universidad Industrial de Santander UIS División de Servicios de Información Estándares de desarrollo Java EE 5.0 ESTÁNDARES DE DESARROLLO PARA LA DIVISIÓN DE SERVICIOS DE INFORMACIÓN DE LA UNIVERSIDAD INDUSTRIAL DE SANTANDER UIS

Estándares DSI - Programación

  • Upload
    rovzu

  • View
    1.078

  • Download
    4

Embed Size (px)

Citation preview

Page 1: Estándares DSI - Programación

1 Universidad Industrial de Santander UIS División de Servicios de Información

Estándares de desarrollo Java EE 5.0

ESTÁNDARES DE DESARROLLO PARA LA DIVISIÓN DE SERVICIOS DE

INFORMACIÓN DE LA UNIVERSIDAD INDUSTRIAL DE SANTANDER UIS

Page 2: Estándares DSI - Programación

2 Universidad Industrial de Santander UIS División de Servicios de Información

Estándares de desarrollo Java EE 5.0

TABLA DE CONTENIDO

1. ENTORNO DE DESARROLLO ................................................................................................... 5

1.1. Java Development Kit JDK .................................................................................................. 5

1.2. Configuración de variables de entorno ............................................................................... 5

1.3. Entorno de desarrollo Integrado IDE ................................................................................... 5

1.4. Servidor de aplicaciones ..................................................................................................... 5

1.5. Jboss Seam ......................................................................................................................... 5

1.6. Servidor de versiones .......................................................................................................... 5

1.7. Espacio de trabajo ............................................................................................................... 6

1.8. Plantillas, estilos, imágenes y formateador ......................................................................... 6

1.9. Patrones a utilizar ................................................................................................................ 6

1.10. Código HTML .................................................................................................................. 7

1.11. Configuración de Librerías .............................................................................................. 7

2. ENTIDADES .............................................................................................................................. 10

2.1. Llaves compuestas. ........................................................................................................... 10

2.2. Sobrescribir los métodos HashCode e Equals .................................................................. 10

2.3. Sobrescribir el método Clone ............................................................................................ 10

3. SERVICIOS ............................................................................................................................... 12

4. LIBRERIAS GENERALES ......................................................................................................... 13

4.1. general-UIS.jar .................................................................................................................. 13

4.2. Log ..................................................................................................................................... 13

4.3. Excepciones ...................................................................................................................... 14

4.4. formato-web.jar .................................................................................................................. 16

5. PATRONES DE DISEÑO .......................................................................................................... 19

5.1. EAO ................................................................................................................................... 19

5.2. Session Façade ................................................................................................................. 21

6. CAPA DE PRESENTACIÓN ..................................................................................................... 22

6.1. Plantilla principal ................................................................................................................ 22

6.2. Contenido .......................................................................................................................... 22

6.3. Paginación ......................................................................................................................... 23

6.4. Texto .................................................................................................................................. 24

6.5. Edición ............................................................................................................................... 25

6.6. Tablas estáticas ................................................................................................................. 26

6.7. Tablas dinámicas ............................................................................................................... 26

6.8. Listas desplegables ........................................................................................................... 26

Page 3: Estándares DSI - Programación

3 Universidad Industrial de Santander UIS División de Servicios de Información

Estándares de desarrollo Java EE 5.0

6.9. Mensajes del sistema ........................................................................................................ 26

7. DECLARACIÓN Y CONTROL DE ACCESO ............................................................................ 27

7.1. Sintaxis generales ............................................................................................................. 27

7.2. Paquetes ........................................................................................................................... 27

7.3. Clases ................................................................................................................................ 28

7.4. Atributos ............................................................................................................................ 28

7.5. Métodos ............................................................................................................................. 29

7.6. Librerias (JAR) ................................................................................................................... 29

7.7. Nombres de archivos......................................................................................................... 29

8. LIBRERIAS Y COMPONENTES JSF........................................................................................ 30

9. ESTRUCTURA DE DIRECTORIOS .......................................................................................... 31

9.1. Consideraciones iníciales .................................................................................................. 31

9.2. Carpetas ............................................................................................................................ 31

9.3. Nombres de archivos......................................................................................................... 32

9.4. Organización del código fuente dentro de la estructura de directorios. ............................ 32

9.5. Documentación .................................................................................................................. 33

10. CÓDIGO FUENTE................................................................................................................. 34

10.1. Nombre de archivos, variables, constantes, atributos, métodos y parámetros. ........... 34

10.2. Comentarios Java: ......................................................................................................... 34

10.3. Orden dentro de los archivos de código fuente: ........................................................... 34

10.4. Especificaciones sobre el formato del código fuente: ................................................... 35

Tabulación: ................................................................................................................................ 35

Longitud de línea ....................................................................................................................... 36

Ruptura de líneas ...................................................................................................................... 36

10.5. DECLARACIONES Y SENTENCIAS ............................................................................ 36

Sentencias package e imports: ................................................................................................. 36

Variables locales: ...................................................................................................................... 36

Clases, interfaces y métodos: .................................................................................................. 36

Sentencias simples:................................................................................................................... 37

Sentencias compuestas: ........................................................................................................... 37

Sentencias if: ............................................................................................................................. 37

Sentencias for: ........................................................................................................................... 38

Sentencias while:....................................................................................................................... 39

Sentencias do-while: ................................................................................................................. 39

Sentencias switch: ..................................................................................................................... 39

Page 4: Estándares DSI - Programación

4 Universidad Industrial de Santander UIS División de Servicios de Información

Estándares de desarrollo Java EE 5.0

Sentencias try-catch: ................................................................................................................. 40

Líneas en blanco ....................................................................................................................... 40

Espacios en blanco: .................................................................................................................. 41

10.6. Sentencias JPQL Y SQL ............................................................................................... 41

Sentencia SELECT.................................................................................................................... 41

Sentencias INSERT, UPDATE Y DELETE (SQL) ..................................................................... 43

Tablas temporales, procedimientos almacenados e índices. ................................................... 43

11. UML ....................................................................................................................................... 44

11.1. Casos de Uso ................................................................................................................ 44

Identificación de Actores ........................................................................................................... 44

Diagrama de Casos de Uso ...................................................................................................... 44

Casos de Uso ............................................................................................................................ 44

11.2. Diagrama de clases ....................................................................................................... 45

12. ANEXO A: VERBOS.............................................................................................................. 46

12.1. Lista de Verbos .............................................................................................................. 46

A nivel de casos de uso ............................................................................................................ 46

A nivel de métodos .................................................................................................................... 47

A nivel de interfaz de usuario .................................................................................................... 48

Page 5: Estándares DSI - Programación

5 Universidad Industrial de Santander UIS División de Servicios de Información

Estándares de desarrollo Java EE 5.0

1. ENTORNO DE DESARROLLO

Todos los programas necesarios se pueden descargar de

192.168.37.41/Compartida/Herramientas.

1.1. Java Development Kit JDK

La versión del JDK es la 1.6, el cual debe ser instalado junto con el JRE en el directorio C:/java1.6.

1.2. Configuración de variables de entorno

Variable JAVA_HOME: Es una variable de entorno que apunta al directorio donde quedó

instalado el JDK. C:/java1.6

Variable PATH: Especifica la ruta de acceso a los archivos ejecutables más importantes

del sistema; la modificación de esta variable permite accesar los ejecutables Java (javac,

javadoc, java) proporcionadas con el JDK de cualquier directorio. C:/java1.6/bin;

1.3. Entorno de desarrollo Integrado IDE

El IDE de desarrollo a utilizar es el JBoss Developer Studio 2.1.0.GA, el cual debe ser instalado

en la carpeta por defecto del instalador.

1.4. Servidor de aplicaciones

El servidor de aplicaciones a utilizar es el jboss-eap-5.0.0.GA, el cual debe ser instalado en la

carpeta C:\jboss-eap-5.0. El Server name en el IDE se debe llamar JBoss 5.0 y el nombre del

JBoss Runtime Enviroment se debe llamar JBoss 5.0.

1.5. Jboss Seam

La versión del Jboss Seam a utilizar es la jboss-seam-2.1.2.GA

1.6. Servidor de versiones

Para su configuración se debe instalar en el JBoss Developer Studio los siguientes paquetes:

subclipse-site-1.4.7

ajdt_1.6.1a_for_eclipse_3.4

Page 6: Estándares DSI - Programación

6 Universidad Industrial de Santander UIS División de Servicios de Información

Estándares de desarrollo Java EE 5.0

org.tmatesoft.svn_1.2.1.eclipse

Una vez instalados se debe solicitar el nombre de usuario y la contraseña al Ingeniero encargado.

Cualquier inquietud acerca de la instalación y configuración del servidor de versiones, dirigirse con

el Ingeniero encargado.

También se debe instalar el siguiente programa: TortoiseSVN-1.5.8.15348-win32-svn-1.5.5.msi

para conectarse con el servidor de versiones de la documentación.

1.7. Espacio de trabajo

El espacio de trabajo se debe crear en C:\workspace.

El nombre del proyecto para los JPA debe estar conformado de la siguiente manera:

[Sistema]Entidades

Por ejemplo: AcademicoEntidades (La primera letra de cada palabra en mayúscula).

El repositorio para los JPA debe estar conformado de la siguiente manera:

[Sistema]JPA

Por ejemplo: AcademicoJPA (La primera letra de cada palabra en mayúscula).

1.8. Plantillas, estilos, imágenes y formateador

Descargar del servidor de versiones de documentación las carpetas Estilos, Plantillas e Imágenes y

copiarlas en la careta view de la aplicación.

1.9. Patrones a utilizar

Los patrones a utilizar corresponden a cada una de las capas implementadas:

Capa de presentación: Modelo Vista Controlador, el cual es implementado por Java Server

Faces (JSF).

Capa de lógica de negocio: Session Façade

Page 7: Estándares DSI - Programación

7 Universidad Industrial de Santander UIS División de Servicios de Información

Estándares de desarrollo Java EE 5.0

Capa de persistencia: Entity Access Object (EAO)

En el capítulo Patrones de diseño, se pueden encontrar ejemplos de implementación de los

patrones Session Façade y EAO.

1.10. Código HTML

Está prohibido el uso de etiquetas HTML en las páginas.

1.11. Configuración de Librerías

Normalmente cuando se crea un proyecto con el framework seam 2.1.2.GA la estructura de

librerías en el EAR y WAR se representa de la siguiente forma:

EAR/lib

antlr-runtime.jar

commons-beanutils.jar

core.jar

drools-compiler.jar

drools-core.jar

groovy-all.jar

janino.jar

jboss-el.jar

jboss-seam-remoting.jar

jbpm-jpdl.jar

mvel14.jar

richfaces-api.jar

WAR/WEB-INF/lib

commons-digester.jar

jboss-seam-debug.jar

jboss-seam-excel.jar

jboss-seam-ioc.jar

jboss-seam-mail.jar

jboss-seam-pdf.jar

jboss-seam-resteasy.jar

jboss-seam-rss.jar

jboss-seam-ui.jar

jsf-facelets.jar

jxl.jar

richfaces-impl.jar

richfaces-ui.jar

# You can remove the JARs for themes you aren't using

darkX.jar

glassX.jar

laguana.jar

Page 8: Estándares DSI - Programación

8 Universidad Industrial de Santander UIS División de Servicios de Información

Estándares de desarrollo Java EE 5.0

Para hace la configuración en los proyectos debemos colocar las librerías de RICHFACES:

- richfaces-api.jar

- richfaces-ui.jar

- richfaces.impl.jar

La librería de FACELETS:

- jsf-facelets.jar

Y por último la librería COMMONS-DIGESTER:

- commons-digester.jar

En la carpeta lib a nivel del archivo EAR. La estructura de librerías debe quedar de la siguiente manera:

EAR/lib

antlr-runtime.jar

commons-beanutils.jar

commons-digester.jar

core.jar

drools-compiler.jar

drools-core.jar

groovy-all.jar

janino.jar

jboss-el.jar

jboss-seam-remoting.jar

jbpm-jpdl.jar

jsf-facelets.jar

mvel14.jar

richfaces-api.jar

richfaces-ui.jar

richfaces-impl.jar

WAR/WEB-INF/lib jboss-seam-debug.jar

jboss-seam-excel.jar

jboss-seam-ioc.jar

jboss-seam-mail.jar

jboss-seam-pdf.jar

jboss-seam-resteasy.jar

jboss-seam-rss.jar

jboss-seam-ui.jar

# You can remove the JARs for themes you aren't using

darkX.jar

glassX.jar

laguana.jar

En el archivo application.xml de proyecto generado por el framework seam se debe hacer

referencia a las librerías RICHFACES y FACELETS, tal como se muestra a continuación.

Page 9: Estándares DSI - Programación

9 Universidad Industrial de Santander UIS División de Servicios de Información

Estándares de desarrollo Java EE 5.0

<?xml version="1.0" encoding="UTF-8"?>

<application xmlns="http://java.sun.com/xml/ns/javaee"

xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

xsi:schemaLocation="http://java.sun.com/xml/ns/javaee

http://java.sun.com/xml/ns/javaee/application_5.xsd"

version="5">

<display-name>Proyecto</display-name>

<module>

<java>/lib/jsf-facelets.jar</java>

</module>

<module>

<java>/lib/richfaces-api.jar</java>

</module>

<module>

<java>/lib/richfaces-ui.jar</java>

</module>

<module>

<java>/lib/richfaces-impl.jar</java>

</module>

<module>

<web>

<web-uri>Proyecto.war</web-uri>

<context-root>/Proyecto</context-root>

</web>

</module>

<module>

<ejb>Proyecto.jar</ejb>

</module>

<!-- Seam and EL -->

<module>

<ejb>jboss-seam.jar</ejb>

</module>

…..

…..

…..

</application>

Las librerías richfaces a usar son las versión 3.3.1. Las cuales deben ser remplazadas en el

proyecto generado por el framework seam.

Page 10: Estándares DSI - Programación

10 Universidad Industrial de Santander UIS División de Servicios de Información

Estándares de desarrollo Java EE 5.0

2. ENTIDADES

Algunas anotaciones requeridas para las entidades se mencionan a continuación:

La Entidad debe llevar las anotaciones: @Entity, @Table y @Name y debe ser una clase

Serializable.

La anotación @Table indica la tabla de la base de datos relacionada para su persistencia.

En la anotación @Entity utilizar el parámetro name para identificar el EJB @Entity(name =

“xxx”).

Los nombres de las clases de Entidad deben ser sustantivos en singular.

Cada entidad debe llevar el atributo serialVersionUID generado por el IDE.

Las anotaciones en la entidad se deben colocar antes del método get correspondiente y no

en la declaración del atributo.

Las anotaciones requeridas para un campo llave son: @Id, @Column.

Las anotaciones requeridas para un campo fecha son: @Column, @Temporal y @NotNull

(Si el campo es obligatorio).

Las anotaciones requeridas para un campo alfanumérico son: @Column, @NotNull (Si el

campo es obligatorio) y @Length.

Las anotaciones requeridas para un campo numérico son: @Column y @NotNull.

2.1. Llaves compuestas.

Se debe utilizar la anotación @EmbeddedId, la cual obliga a declara un objeto del tipo de la llave

dentro del EJB de entidad.

2.2. Sobrescribir los métodos HashCode e Equals

Se debe utilizar únicamente los campos que conforman la llave primaria. En el caso de las llaves

compuestas, el atributo que hace referencia a ésta.

2.3. Sobrescribir el método Clone

Este método se debe sobrescribir cuando se desea obtener una copia del objeto original, para

hacer posibles modificaciones al objeto copia sin reflejar cambios en el objeto original

Nota: Para utilizar los JPA externos (academico.jar, recursos-humanos.jar, etc), éstos deben

copiarse en la carpeta raíz. En el caso de Windows C:\, para Linux \). En cada uno de los archivos

persistence.xml de su aplicación, se debe utilizar <jar-file>file:/jpa.jar</jar-file>.

Page 11: Estándares DSI - Programación

11 Universidad Industrial de Santander UIS División de Servicios de Información

Estándares de desarrollo Java EE 5.0

Por ejemplo:

<jar-file>file:/academico.jar</jar-file>

<jar-file>file:/recursos-humanos.jar</jar-file>

<jar-file>file:/general-UIS.jar</jar-file>

Page 12: Estándares DSI - Programación

12 Universidad Industrial de Santander UIS División de Servicios de Información

Estándares de desarrollo Java EE 5.0

3. SERVICIOS

Para crear un servicio se debe tener en cuenta las siguientes reglas:

La interfaz debe contener la anotación Remote

La implementación de la interfaz debe contener la anotación RemoteBinding con su

respectivo nombre jndi (igual al utilizado por la anotación Name). Por ejemplo:

@RemoteBinding(jndiBinding = "ConsultarGenerales")

Para utilizar el servicio se debe utilizar la anotación EJB indicando el nombre jndi. De acuerdo al

ejemplo anterior sería:

@EJB(mappedName = "ConsultarGenerales")

Page 13: Estándares DSI - Programación

13 Universidad Industrial de Santander UIS División de Servicios de Información

Estándares de desarrollo Java EE 5.0

4. LIBRERIAS GENERALES

4.1. general-UIS.jar

Implementa métodos estándar para el manejo de errores, excepciones. Puede descargarse la

documentación y la librería del servidor de versiones utilizando la herramienta TortoiseSNV en la

carpeta Java 5 / Librerias.

4.2. Log

Agregar al proyecto la librería log4j.jar, además se debe incluir el siguiente atributo en la clase:

private Log log;

Se debe instanciar este atributo, ya sea en su declaración o en el constructor:

log = new Log(“[nombreAplicacion]”);

Donde nombreAplicacion es el nombre de su aplicación y con el cual va a identificar el archivo de

logs. Por ejemplo:

private Log log = new Log(“presupuesto”);

Esta sentencia genera un archivo llamado presupuesto.html en server/default/log, donde estarán

almacenados los logs de esta aplicación.

Nota. Es importante instanciar este atributo, ya que garantiza la impresión de errores de la

aplicación. El uso de system.out.println u otros parecidos está prohibido.

Para crear un mensaje de error basta con utilizar la variable log incluyendo cualquiera de estas

líneas (Se puede encontrar más información en Internet consultando log4j):

log.getLog.error(mensaje);

log.getLog.info(mensaje);

Page 14: Estándares DSI - Programación

14 Universidad Industrial de Santander UIS División de Servicios de Información

Estándares de desarrollo Java EE 5.0

4.3. Excepciones

Primero se debe copiar el archivo xfire-all-1.2.6.jar a la carpeta lib del proyecto y a la carpeta lib

del servidor.

Los métodos que son declarados en la interfaz del EAO, deben lanzar la excepción DSIException.

Por ejemplo:

public List<TipoDocumento> getTiposDocumentos(List<Short> codigos) throws DSIException;

En la clase EAO, la implementación del método de ejemplo es:

public List<TipoDocumento> getTiposDocumentos(List<Short> codigos) throws DSIException {

List<TipoDocumento> tiposDocumento = null;

try {

} catch (Exception e) {

throw new DSIException(e);

}

return tiposDocumento;

}

Para capturar las posibles excepciones que lanza el método, se utiliza el try - catch, y en el catch la

Exception. Dentro del catch se lanza la excepción DSIExcepcion pasando como argumento la

variable de la excepción.

Siguiendo con el ejemplo, en el EJB, la llamada al método getTiposDocumentos debe realizarse

dentro del try – catch de la siguiente manera:

try {

this.tiposDocumento = autorizarPagosEAO.getTiposDocumentos(null);

} catch (DSIException e) {

log.getLog().error(e.toString());

}

Los métodos que se implementen en el EAO como privados, no deben capturar la excepción, la

deben lanzar.

Para los métodos que manejen transacciones UPDATE, DELETE E INSERT, es necesario utilizar

el método flush() del EntityManager, para provocar la excepción antes del commit. Por ejemplo:

Page 15: Estándares DSI - Programación

15 Universidad Industrial de Santander UIS División de Servicios de Información

Estándares de desarrollo Java EE 5.0

public void setTipoDocumento(TipoDocumento aDocumento, boolean isNuevo) throws DSIException {

try {

if(isNuevo){

em.persist(aDocumento);

} else {

em.merge(aDocumento);

}

em.flush();

} catch (Exception e) {

throw new DSIException(e);

}

}

public void eliminarPais(Pais aPais) throws DSIException {

try {

em.remove(aPais);

em.flush();

} catch (Exception e) {

throw new DSIException(e);

}

}

La clase DSIExcepcion, permite crear otras excepciones personalizadas y para ello existen

diferentes constructores para la clase, algunos de ellos reciben la llave para leer el mensaje del

archivo del idioma general o específico.

La clase DSIPrivilegioException permite manejar excepciones personalizadas para los privilegios

de la aplicación. Esta clase maneja cuatro tipo de excepciones: SELECT, INSERT, UPDATE y

DELETE.

Este tipo de excepción se debe lanzar en los métodos del EAO que ameriten su validación. Por

ejemplo:

throw new DSIPrivilegioException(DSIPrivilegio.PRIV_INSERT,"Estudiantes");

Se la pasa el tipo de excepción que se desea tratar y un argumento que se le concatena al

mensaje genérico. El mensaje sin argumento quedaría así:

Usted no tiene suficientes Privilegios para agregar {0} en el Sistema.

Con Argumento:

Usted no tiene suficientes Privilegios para agregar Estudiantes en el

Sistema.

Page 16: Estándares DSI - Programación

16 Universidad Industrial de Santander UIS División de Servicios de Información

Estándares de desarrollo Java EE 5.0

Al igual que la DSIException, también se permite crear excepciones personalizadas.

Como un método puede lanzar las dos excepciones (DSIException y DSIPrivilegioException) es

necesario hacer diferencia entre las dos (en el EJB). Para realizar esto se debe usar el operador

instanceof. Por ejemplo:

try {

this.tiposDocumento = autorizarPagosEAO.getTiposDocumento(null);

} catch (DSIException e) {

if(e instanceof DSIPrivilegioException){

log.getLog().error(e.toString());

} else {

log.getLog().error(e.toString());

}

}

Es importante resaltar que los mensajes de error que el usuario ve en la capa de presentación, son

enviados a través del StatusMessages ubicado en el catch del método en el EJB y de acuerdo al

archivo de idioma utilizado. Por ejemplo:

try {

this.tiposDocumento = autorizarPagosEAO.getTiposDocumento(null);

} catch (DSIException e) {

if(e instanceof DSIPrivilegioException){

StatusMessages.instance().add(FormatoWeb.getMensaje(„ErrorPrivilegio‟, true));

log.getLog().error(e.toString());

} else {

StatusMessages.instance().add(FormatoWeb.getMensaje(„ErrorConsulta‟, true));

log.getLog().error(e.toString());

}

}

4.4. formato-web.jar

Esta librería contiene la clase FormatoWeb, la cual es la encargada de dar formato a las fechas,

números, caracteres especiales e idioma.

Para utilizar la clase se debe modificar el archivo build.xml de la aplicación adicionando las

siguientes líneas dentro de la etiqueta <target name="war"…/>

<target name="war"…/>

<copy todir="${ear.dir}">

<fileset dir="${basedir}/resources">

<include name="messages*.properties"/>

</fileset>

</copy>

Page 17: Estándares DSI - Programación

17 Universidad Industrial de Santander UIS División de Servicios de Información

Estándares de desarrollo Java EE 5.0

</target>

Y en la etiqueta <target name="ear" … />

<target name="ear" … />

<copy todir="${ear.dir}">

<fileset dir="${lib.dir}">

<include name="formato-web.jar" />

</fileset>

</copy> </target>

En el archivo application.xml incluir las siguientes líneas:

<module>

<ejb>formato-web.jar</ejb>

</module>

En el archive components.xml incluir la siguiente línea:

<component class="co.edu.uis.servicios.FormatoWeb"/>

La sintaxis en la capa de presentación es:

#{FormatoWeb.[nombreMetodo](parámetro)}

Donde nombreMetodo es el nombre del método a utilizar y parámetro es el valor a mostrar. Por

ejemplo:

#{FormatoWeb.fechaCorta(usuario.fechaCreacion)}

Para el manejo del idioma se debe descargar del servidor de versiones de documentación el

archivo messages_es_CO.properties ubicado en la carpeta Idioma y copiarlo a la carpeta

resources de su proyecto.

Page 18: Estándares DSI - Programación

18 Universidad Industrial de Santander UIS División de Servicios de Información

Estándares de desarrollo Java EE 5.0

Adicionalmente se debe crear un archivo llamado messages_es_CO_APLICACION.properties,

en la misma ubicación, con las etiquetas propias de la aplicación.

Para mostrar una etiqueta en la página se debe utilizar la siguiente sintaxis:

#{FormatoWeb.getMensaje( „etiqueta‟, [ true | false ] )}

Donde etiqueta es el nombre de alguna de las etiquetas en el archivo de idioma. Si el segundo

parámetro es true la etiqueta se busca en el archivo general messages_es_CO.properties. Si es

false se busca en el archivo de la aplicación messages_es_CO_APLICACION.properties. Por

ejemplo:

#{FormatoWeb.getMensaje( „primerNombre‟, true )}

La etiqueta primerNombre se busca en el archivo general y en pantalla se visualiza el valor

correspondiente a ésta.

Para mayor información consultar la documentación JavaDoc de la clase.

Page 19: Estándares DSI - Programación

19 Universidad Industrial de Santander UIS División de Servicios de Información

Estándares de desarrollo Java EE 5.0

5. PATRONES DE DISEÑO

A continuación se muestra un ejemplo de cómo implementar los patrones de diseño Session

Façade y EAO.

5.1. EAO

En la interfaz EAO deben estar la firma de los métodos que se desean implementar en la clase

EAO y los cuales serán llamados desde la clase EJB. La única anotación requerida para la interfaz

es la @Local.

package co.edu.uis.prueba; import javax.ejb.Local; @Local public interface PruebaEAO {

public void registrarCondicionalidad (Condicionalidad aCondicionalidad) throws

DSIException;

}

Es necesario utiliza la sentencia throws, esta se utiliza al final de la declaración del método e

indica que la clase de Excepciones DSIException va a tener que ser implementada en el método

que invoque al método que tenga throws, es decir la clase EJB.

En la clase EAO se debe usar las anotaciones: @Stateless y @Name. El EntityManager debe ser

inyectado por SEAM utilizando la anotación @In.

package co.edu.uis.prueba; import javax.ejb.Stateless; import org.jboss.seam.annotations.In; import org.jboss.seam.annotations.Name; import co.edu.uis.academico.entidades.Condicionalidad; @Stateless @Name(“pruebaEAO”) public class PruebaEAOImp implements PruebaEAO { @In private EntityManager em;

public void registrarCondicionalidad (Condicionalidad aCondicionalidad) throws

DSIException{ try{

em.persist(aCondicionalidad); em.flush();

Page 20: Estándares DSI - Programación

20 Universidad Industrial de Santander UIS División de Servicios de Información

Estándares de desarrollo Java EE 5.0

}catch(Exception e){

throw new DSIException(e);

}

} }

Para el funcionamiento correcto del @In en la clase EAO, se debe configurar el contexto de

persistencia en el archivo components.xml.

persistence:managed-persistence-context

name="em"

auto-create="true"

persistence-unit-jndi-name="x"/>

Donde x es el nombre del JNDI Java Naming Directory Interface, que está en el archivo

persistence.xml.

Adicionalmente se debe agregar al final del archivo components.xml: <ui:jpa-entity-loader entity-manager="#{em}" />

En la clase EAO NO se debe declarar atributos a nivel de clase excepto el EntityManager. Se

debe usar la lista de verbos como: crearXxxxx, eliminarXxxxx y modificarXxxx para los métodos de

transacción a la base de datos. Para los métodos de consulta a la base de datos se debe usar el

prefijo get. Ejemplo: getProgramasAcademicos(parámetros [opcional]) si este método retorna

un listado, en caso de retornar un objeto será: getProgramaAcademico(parámetros[opcional]).

Para realizar consultas a la base de datos se debe utilizar las funciones de Hibernate, las cuales

permiten interactuar con las entidades para realizar búsquedas.

Primero se debe crear el objeto sesión de Hibernate, el cual toma la conexión del EntityManager:

org.hibernate.Session sesion = (org.hibernate.Session)em.getDelegate();

Con el objeto anterior se crea el siguiente objeto de tipo Criteria, el cual asigna la clase y ofrece la

posibilidad de adicionar condiciones a la consulta:

Criteria criterios = sesion.createCriteria([Nombre de la clase].class);

Para adicionar condiciones se debe hacer de la siguiente manera:

criterios.add(Restrictions.like("[Atributo de la clase]" , valor));

Page 21: Estándares DSI - Programación

21 Universidad Industrial de Santander UIS División de Servicios de Información

Estándares de desarrollo Java EE 5.0

Para retornar la lista de resultados se utiliza:

criterios.list();

También se puede limitar la consulta:

criterios.setMaxResults(100);

5.2. Session Façade

La interfaz EJB solo lleva la firma de los métodos que son implementados en la clase EJB y

aquellos métodos que son llamados desde la capa de presentación de JSF, la única anotación

requerida es: @Local.

package co.edu.uis.prueba; import javax.ejb.Local; @Local public interface Prueba { public void registrar(String aCodigo, string aNombre); }

La clase EJB debe usar las anotaciones @Stateful, @Scope y @Name, en esta clase se desarrolla

la lógica de negocio y llama los métodos del EAO.

package co.edu.uis.prueba; import javax.ejb.Stateful; import org.jboss.seam.ScopeType; import org.jboss.seam.annotations.Name; import co.edu.uis.academico.entidades.Condicionalidad; @Stateful @Scope(ScopeType.Conversation) @Name(“prueba”) public class PruebaEJB implements Prueba { @EJB private PruebaEAO pruebaEAO; public void registrar(String aCodigo, String aNombre) { Condicionalidad condicionalidad = new Condicionalidad(aCodigo,aNombre); … … Lógica del negocio Condicionalidad condicionalidad = pruebaEAO.registrar(condicionalidad);

} }

Page 22: Estándares DSI - Programación

22 Universidad Industrial de Santander UIS División de Servicios de Información

Estándares de desarrollo Java EE 5.0

6. CAPA DE PRESENTACIÓN

6.1. Plantilla principal

La plantilla principal de una página es la siguiente:

6.2. Contenido

Esta sección se refiere al caso de uso implementado. La estructura de esta sección es:

ENCABEZADO GENERAL DE LA UIS

MENU

Barra de navegación

CONTENIDO

Menú de opciones

Menú de opciones del registro seleccionado

FILTROS

DATOS

CONTENIDO DEL REGISTRO SELECCIONADO

FaccesMessages

Page 23: Estándares DSI - Programación

23 Universidad Industrial de Santander UIS División de Servicios de Información

Estándares de desarrollo Java EE 5.0

Para las páginas que muestran formularios

6.3. Paginación

Para la paginación se debe tener en cuenta el tipo de consulta que se va a realizar y la memoria

consumida por ésta en el servidor de base de datos. De acuerdo a esto la aplicación decide el

número de registros máximos que debe retornar la consulta.

Por ejemplo, se quiere consultar los estudiantes de la sede Bucaramanga. De acuerdo al análisis

realizado, no hay un consumo alto de memoria, por lo que se decide retornar 100 estudiantes

máximos. Esto indica que cuando se implemente el método de consulta en JPQL, el parámetro

setMaxResults debe tener el valor de 100.

Para su implementación en la capa de presentación se debe utilizar el control datascroller, de

richfaces, con 20 registros por página. Por ejemplo:

<h:form>

<a:outputPanel id="tblTabla">

<rich:dataTable value="#{condicionalidades}"

var="v"

rendered="#{condicionalidades != null and

condicionalidades.rowCount > 0}"

width="100%" onRowMouseOver="this.style.backgroundColor='#E1E1E1'"

onRowMouseOut="this.style.backgroundColor=

'#{a4jSkin.tableBackgroundColor}'"

id="dtbCondicionalidades"

rows="20">

<f:facet name="header">

Menú de opciones

TITULO CON EL IDENTIFICADOR CORRESPONDIENTE

FORMULARIO CENTRADO

Messages

Page 24: Estándares DSI - Programación

24 Universidad Industrial de Santander UIS División de Servicios de Información

Estándares de desarrollo Java EE 5.0

<rich:columnGroup>

<rich:column width="15%">

<rich:spacer></rich:spacer>

</rich:column>

<rich:column

width="85%">#{FormatoWeb.getMensaje(‘descripcion’,true)}

</rich:column>

</rich:columnGroup>

</f:facet>

<rich:column width="15%">

<div align="center">

<h:outputText value="#{v.codigo}" />

</div>

</rich:column>

<rich:column width="85%">

<div align="left">

<h:outputText value="#{v.descripcion}" />

</div>

</rich:column>

<f:facet name="footer">

<rich:datascroller

id=”dscCondicionalidades”>

<f:facet name="next">

<h:outputText

value="#{FormatoWeb.getMensaje(‘siguiente’,true)}" />

</f:facet>

<f:facet name="previous">

<h:outputText

value="#{FormatoWeb.getMensaje(‘anterior’,true)}" />

</f:facet>

</rich:datascroller> </f:facet>

</rich:dataTable>

</a:outputPanel>

</h:form>

6.4. Texto

Existen cinco tipos de plantillas para mostrar texto en la página. Éstas se encuentran dentro de la

carpeta Plantillas.

etiqueta.xhtml: Texto o datos.

etiquetaColumna.xhtml: El título de la columna en una tabla

titulo.xhtml: Titulos

etiquetaNavegacion.xhtml: Utilizado en la barra de navegación

Page 25: Estándares DSI - Programación

25 Universidad Industrial de Santander UIS División de Servicios de Información

Estándares de desarrollo Java EE 5.0

mostrar.xhtml: Permite visualizar dos etiquetas (etiqueta, dato) al mismo tiempo. Su

objetivo es la de visualizar datos como si fuera un formulario.

La sintaxis para utilizar las plantillas son:

<s:decorate template="../Plantillas/[nombrePlantilla]">

<ui:define name="label">

#{FormatoWeb.getMensaje(„primerNombre‟, true)}

</ui:define>

</s:decorate>

Donde nombrePlantilla puede ser etiqueta.xhtml, etiquetaColumna.xhtml, etiquetaTitulo.xhtml,

etiquetaNumeros.xhtml o etiquetaNavegacion.xhtml.

Para la plantilla mostrar.xhtml:

<s:decorate template="../Plantillas/mostrar.xhtml">

<ui:define name="label">

#{FormatoWeb.getMensaje(„primerNombre‟, true)}

</ui:define>

<h:outputText value="#{formatoWeb.usuario.primerNombre}"/>

</s:decorate>

6.5. Edición

Para capturar cualquier tipo de dato en una caja de texto se debe utilizar la plantilla edicion.xhtml

de la siguiente manera:

<s:decorate id="dcr[identificador]" template="/plantillas/edicion.xhtml">

<ui:define name="label">

#{FormatoWeb.getMensaje(„primerNombre‟, true)}

</ui:define>

<h:inputText id="txt[nombreCajaDeTexto]" value="[valor]"

required="true">

<a:support event="onblur" reRender="dcr[identificador]"/>

</h:inputText> </s:decorate>

dcr[identificador] es el nombre del elemento decorate. Por ejemplo: dcrPrimerNombre.

txt[nombreCajaDeTexto] es el nombre de la caja de texto. Por ejemplo: txtPrimerNombre.

Page 26: Estándares DSI - Programación

26 Universidad Industrial de Santander UIS División de Servicios de Información

Estándares de desarrollo Java EE 5.0

6.6. Tablas estáticas

Se debe usar el control panelGrid de Java Server Faces.

6.7. Tablas dinámicas

Se debe usar el control dataTable de Rich Faces, agregando las siguientes líneas de programación

en su definición:

onRowMouseOver="this.style.backgroundColor='#E1E1E1'"

onRowMouseOut="this.style.backgroundColor='#{a4jSkin.tableBackgroundColor}'

Las cuales indican el color de la fila cuando el puntero del mouse esta sobre ésta.

6.8. Listas desplegables

Para cualquier tipo de lista se debe utilizar el control de Java Server Faces.

6.9. Mensajes del sistema

Los mensajes del sistema son textos enviados por los EJB de sesión, ya sea de confirmación de

una acción o errores en el procedimiento. Dichos errores se deben mostrar en la etiqueta

StatusMessages la cual debe estar definida al comienzo de la página después del menú si existiera

éste. El código es el siguiente:

<h:messages globalOnly="true" styleClass="message"/>

Para mostrar errores de validación en los formularios, éstos deben aparecer al frente de cada

control y no globalmente.

Page 27: Estándares DSI - Programación

27 Universidad Industrial de Santander UIS División de Servicios de Información

Estándares de desarrollo Java EE 5.0

7. DECLARACION Y CONTROL DE ACCESO

A continuación se presentan los aspectos más importantes que se deben tener en cuenta al

momento de crear una clase o método y el control de acceso para los atributos de la misma.

7.1. Sintaxis generales

Todos los nombres de los identificadores deben estar en español.

Siempre se deben utilizar nombres que sean claros, concretos y libres de ambigüedades.

Usando palabras completas evitando acrónimos y abreviaturas.

Los nombres deben estar definidos sin espacios en blanco, sin guiones ( _ , -), ni comillas (

“,‟ ), sin operadores ( +, - , / , *), sin tildes, utilizar la n en vez de la ñ y sin caracteres

especiales.

No se debe utilizar la mayúscula para diferenciar entre identificadores distintos. Ejemplo:

contador y Contador.

No se deben diferenciar dos identificadores solo con numerales en cualquier posición.

Ejemplo: contador1, contador2, 1contador, 2contador.

Las siguientes partículas están prohibidas en la declaración de los nombres de

identificadores: artículos (el, la, los, unos, unas, un), determinantes demostrativos (este,

ese, aquel, aquellos), cardinales (uno, dos, etc.), pronombres de cualquier tipo (yo, tu, el,

me, te, se, este, ese, mi, tu, su, etc.).

Se deben utilizar máximo 5 palabras por nombre, las 3 primeras palabras van completas, a

partir de la cuarta palabra se quitan las vocales a la palabra exceptuando la última vocal y

la primera si la palabra empieza por vocal. No se utiliza ningún separador entre las

palabras, se separa cada palabra utilizando su primera letra en mayúscula. Ejemplo:

hacerMantenimientoConsultaUsros, hacerMantenimientoAsignaturasCntxto.

7.2. Paquetes

El nombre de los paquetes debe iniciar con minúscula la primera palabra, las siguientes

palabras inician en mayúscula, sin separadores.

La estructura de los paquetes es la siguiente:

co.edu.uis.[sistema].[aplicación].[módulo].[caso de uso]

Ejemplo: co.edu.uis.financiero.egresos.contratacion.ordenarPrestacionServicio.

La estructura para el paquete donde van a estar las entidades comunes para todos los

sistemas es el siguiente: co.edu.uis.sistema.entidades

Page 28: Estándares DSI - Programación

28 Universidad Industrial de Santander UIS División de Servicios de Información

Estándares de desarrollo Java EE 5.0

La estructura para el paquete donde van a estar los servicios comunes para todos los

sistemas es el siguiente: co.edu.uis.sistema.servicios

7.3. Clases

Los nombres de las clases deben iniciar siempre en mayúscula, deben ser simples y

descriptivos.

Los nombres de los EJB utilizados por el patrón Session Façade está conformado por un

verbo autorizado (Ver anexo de verbos). Además debe incluir al final las letras “EJB”.

Ejemplo: RegistrarMatriculaEstudianteEJB.

La interfaz asociada al EJB debe llevar el mismo nombre del EJB sin el sufijo “EJB”.

Ejemplo: RegistrarMatriculaEstudiante.

El nombre de los EJB utilizados por el patrón EAO está conformado por un verbo

autorizado. Además debe incluir al final las letras “EAOImp”. Por ejemplo:

RegistrarMatriculaEstudianteEAOImp.

La interfaz asociada al EAO debe llevar el mismo nombre del EJB sin el sufijo “Imp”.

Ejemplo: RegistrarMatriculaEstudianteEAO.

Para los EJB de entidad, cuando la clase representa una relación entre dos entidades, el

nombre se forma uniendo los nombres de las entidades involucradas.

El nombre de la clase no contendrá detalles sobre la implementación interna de la misma.

Por ejemplo ArrayEstudiantes no es nombre válido.

7.4. Atributos

Para el nombre de las atributos utilizar palabras completas en singular (máximo tres

palabras). El nombre deber ir en plural cuando la variable representa una lista o un

conjunto de elementos.

Si las palabras no son suficientes para la descripción, se debe hacer un comentario, al

frente de la variable.

Las constantes (final) van en mayúscula sostenida separando las palabras por guión de

piso ( _ ).

Para los argumentos, deben iniciar siempre con la letra “a” y posteriormente el nombre

según lo establecido anteriormente.

Para las instancias de las clases, las entidades llevan el mismo nombre de la clase, solo

que la palabra inicial va en minúscula. Si se necesita más de una instancia, para

diferenciarlas se debe adicionar una palabra que identifique el rol que desempeña.

Ejemplo: Estudiante estudiantePregrado, Estudiante estudiantePostgrado.

Page 29: Estándares DSI - Programación

29 Universidad Industrial de Santander UIS División de Servicios de Información

Estándares de desarrollo Java EE 5.0

Los atributos de tipo booleano deben usar el prefijo is.

Todos los atributos declarados a nivel de clase deben ser privados.

7.5. Métodos

Se deben utilizar los verbos autorizados para su codificación.

El nombre de los métodos debe iniciar con minúscula la primera palabra, las siguientes

palabras inician en mayúscula, sin separadores.

La primera palabra del nombre de los métodos debe ser un verbo en infinitivo y debe

representar una acción o comportamiento de la clase.

El nombre del método debe describir claramente el comportamiento del mismo.

En lo posible no se deben usar verbos genéricos aplicables a todo como: procesar,

gestionar, manejar. Ejemplo: procesarEstudiante(), gestionarCliente(), en este caso el

verbo no aclara el cometido real del método.

Para los métodos que retornan objetos(s) se usa el prefijo get. Ejemplo:

getProgramasAcademicos(parámetros [opcional]) si este método retorna un listado, en

caso de retornar un objeto será: getProgramaAcademico(parámetros[opcional]).

Se debe colocar el modificador de visibilidad private para los métodos que son invocados

desde la misma clase.

En la clase EJB se debe hacer uso de los métodos privados para ser invocados desde los

métodos get.

7.6. Librerias (JAR)

El nombre de las librerías no sigue el mismo estándar de las clases. Éstas se deben escribir en

minúscula, separando cada palabra con un guión (-). Ejemplo: recursos-humanos.jar.

7.7. Nombres de archivos

Se sigue el mismo estándar descrito en las reglas de sintaxis generales.

Page 30: Estándares DSI - Programación

30 Universidad Industrial de Santander UIS División de Servicios de Información

Estándares de desarrollo Java EE 5.0

8. LIBRERIAS Y COMPONENTES JSF

El nombre de las variables a utilizar para reconocer las librerías utilizadas en las páginas debe ser así:

s para taglib Ejemplo: xmlns:s="http://jboss.com/products/seam/taglib"

ui para facelets Ejemplo: xmlns:ui="http://java.sun.com/jsf/facelets"

f para core Ejemplo: xmlns:f="http://java.sun.com/jsf/core"

h para jsf/html Ejemplo: xmlns:h="http://java.sun.com/jsf/html"

rich para richfaces Ejemplo: xmlns:rich="http://richfaces.org/rich"

a para richfaces a4j Ejemplo: xmlns:a="http://richfaces.org/a4j"

Para los nombres de los controles se coloca el prefijo correspondiente al control seguido del nombre.

Control Prefijo Ejemplo

Formulario frm frmFormatoInscripcion

Botón btn btnConsultar

Caja de texto txt txtPrimerNombre

Lista – Combo lst (Primera letra: L minúscula) lstColegios

OutputText (JSF) out outDescripcion

Check box chk chkRespuesta

Radio button rdb rdbEstadoCivil

Hidden hid hidCodigo

Imagen img imgEscudo

Panel (RichFaces) pnl (Tercera letra: L minúscula) pnlPanelPrincipal

Tabla tbl ((Tercera letra: L minúscula) tblEstudiantes

Div div divFormato

Decorate (taglib) dcr[Nombre control sin prefijo] dcrPrimerNombre

Ancla anc ancPrimeraParte

ToolBar (RichFaces) tbar tbarHerramientas

ToolBarGroup (RichFaces) tbg tbgGrupoHerramientas

DataScroller dsc dscCondicionalidades

DataTable dtb dtbEstudiantes

Page 31: Estándares DSI - Programación

31 Universidad Industrial de Santander UIS División de Servicios de Información

Estándares de desarrollo Java EE 5.0

9. ESTRUCTURA DE DIRECTORIOS

9.1. Consideraciones iníciales

Para cada uno de los sistemas principales (Recursos Humanos, Financiero, Académico,

etc.) se debe crear un proyecto que debe seguir los estándares para la estructura de

directorios y nombres. En estos proyectos van las entidades propias de cada sistema, así

como los componentes comunes a varias aplicaciones.

Las entidades van en cada sistema empaquetado en un .jar, de tal manera que el

desarrollo de una nueva aplicación no implica la implementación de éstas.

En el paquete general van los elementos que son utilizados por todos los módulos.

Las entidades van a estar todas en co.edu.uis.[Sistema].entidades.

Los servicios van a estar todos en co.edu.uis.[Sistema].servicios.

Para la creación de las entidades se toma la estructura de la base de datos. Por lo tanto se

hace indispensable comenzar por este paso, seguido de la creación de los componentes

para posteriormente desarrollar las demás aplicaciones.

9.2. Carpetas

Deben comenzar con minúscula y están basados en la estructura de directorios que se genera

mediante “Seam-Gen” cuando se crea un nuevo proyecto. Las carpetas que se crean son las

siguientes:

bootstrap

classes

dist

exploded-archives

lib

nbproject

resources

src

hot

main

test

Page 32: Estándares DSI - Programación

32 Universidad Industrial de Santander UIS División de Servicios de Información

Estándares de desarrollo Java EE 5.0

test-build

view

A continuación se hace una breve descripción de las carpetas con las que el desarrollador tendrá

contacto directo.

Carpeta src. En esta carpeta se guardan los archivos fuentes de las clases del sistema

distribuidos en dos subcarpetas de la siguiente manera:

Carpeta main. Contiene las clases de apoyo al proceso. No incluye a las entidades, pues

estas estarán disponibles en otro lugar que se describe más adelante en este documento.

Carpeta hot. Contiene los casos de uso reflejados en los EJBs y sus interfaces.

Carpeta resources. Contiene los archivos de configuración de la aplicación.

Carpeta view. Contiene las páginas, imágenes, estilos y todo lo referente a aspecto de la

aplicación.

Carpeta dist. Contiene los archivos jar, war y ear de la aplicación. Estos se generan

automáticamente.

Carpeta lib. Contiene las librerías necesarias para la ejecución de la aplicación.

9.3. Nombres de archivos

Se sigue el mismo estándar dado para el nombre de variables descrito en el capítulo 7 de este

documento.

9.4. Organización del código fuente dentro de la estructura de directorios.

Paquetes. La composición del nombre de los paquetes teniendo en cuenta la siguiente

sintáxis: co.edu.uis.[sistema].[aplicación].[módulo].[caso de uso].

Ejemplo:

co.uis.edu.co.recursosHumanos.catedra.solicitudesNombramiento.aprobacionViceAcdmca

En el caso de los proyectos principales (los que empaquetan entidades y componentes para cada

sistema) los paquetes serán los siguientes:

Administración (src/action): co.edu.uis.[Sistema].[Aplicación].administracion

Clases generales (src/action): co.edu.uis.[Sistema].[Aplicación].general

Page 33: Estándares DSI - Programación

33 Universidad Industrial de Santander UIS División de Servicios de Información

Estándares de desarrollo Java EE 5.0

Paginas (carperta view)

Dentro de esta carpeta se tendrán las siguiente estructura:

Plantillas Plantillas del sitio

imagenes

estilos

scripts Si son necesarios. No es obligatorio y se deben evitar en la medida de lo

posible.

administración Todo lo referente a la administración

generales Páginas de uso global en la aplicación

ayudas

modulos

9.5. Documentación

La documentación relacionada con el diseño del sistema reside en la base de datos de Enterpirse

Architect.

La documentación del código fuente se debe hacer en cada una de las clases, siguiendo el

estándar de JAVADOC y documentando la definición de la clase, descripción de los métodos get y

set y descripción de los parámetros de entrada y salida de cada uno de los métodos que

componen la clase.

Page 34: Estándares DSI - Programación

34 Universidad Industrial de Santander UIS División de Servicios de Información

Estándares de desarrollo Java EE 5.0

10. CÓDIGO FUENTE

10.1. Nombre de archivos, variables, constantes, atributos, métodos y parámetros.

Los nombres dentro del código fuente siguen los parámetros establecidos en el estándar general

de nombres, con las siguientes particularidades.

Los nombre de los parámetros de los métodos empiezan con guión de piso, el resto del

nombre sigue el estándar para nombres de variables. Una vez dentro del código fuente, se

deben asignar a una nueva variable con el mismo nombre pero sin el guión de piso.

Los nombres de constantes o variables finally, se escriben en mayúscula sostenida

separando las palabras por guiones de piso.

10.2. Comentarios Java:

Los programas en Java pueden tener dos tipos de comentarios: comentarios de implementación

y comentarios de documentación. Los comentarios de implementación están delimitados por /*..

*/ cuando se trata de varias líneas y // cuando se trata de una línea. Los comentarios de

documentación (conocidos como "comentarios Javadoc") son específicos de Java y están

delimitados por /** ... */. Los comentarios de documentación se pueden extraer a ficheros HTML

usando la herramienta javadoc.

Los comentarios de implementación están destinados a comentar el código o para comentarios

sobre la implementación en particular, buscan dar una orientación y hacer aclaraciones sobre la

implementación a quien observa el código fuente. Los comentarios de documentación están

destinados a describir la especificación del código, desde una perspectiva independiente de la

implementación, están hechos para ser leídos por desarrolladores que pueden no tener

necesariamente el código fuente a mano.

Los comentarios se deben usar para dar una visión general del código y para proporcionar

información adicional que no esté disponible fácilmente en el propio código.

Evitar duplicar información que esté presente (y de forma clara) en el código.

10.3. Orden dentro de los archivos de código fuente:

Cada archivo de código fuente Java debe contener una única clase o interfaz pública y deben

seguir el siguiente orden:

Sentencias package.

Sentencias import.

Page 35: Estándares DSI - Programación

35 Universidad Industrial de Santander UIS División de Servicios de Información

Estándares de desarrollo Java EE 5.0

Comentario de documentación de la clase/interfaz.

Declaraciones de clase e interfaz.

Comentario de la implementación de la clase/interfaz si fuera necesario.

Declaración de constantes (solo se declaran dentro de interfaces).

Declaración de atributos. (la declaración se debe hacer uno por línea y al frente debe ir un

comentario de implementación de ser necesario.)

Declaración de variables. (En nuestro estándar no se deben declarar variables públicas,

para ello se definen los métodos gets() y sets()). Las variables aquí declaradas serán

privadas y se utilizarán como indicadores de estado de la clase. Las variables se deben

declarar en el siguiente orden:

o Variables estáticas: organizadas por ámbito o accesibilidad de la siguiente manera:

públicas, protegidas, de paquete (sin modificador) privadas.

o Variables de instancia: organizadas de la misma manera que las estáticas.

o Al igual que los atributos se debe declarar una por línea para facilitar los

comentarios de implementación frente a ellas en caso de necesitarse.

Comentario de documentación sobre cada uno de los constructores (no aplica a

entidades).

Declaración de constructores. (Siempre se declarará el constructor sin parámetros, se

requiera o no una acción dentro de este. No aplica a entidades).

Declaración de métodos gets() , sets() e is().

Comentario de documentación sobre cada uno de los métodos que lo requieran.

Declaración de métodos del la lógica del negocio: estos deben ir agrupados por

funcionalidad en lugar de por ámbito, siendo el objetivo de esta organización el hacer el

código de más fácil lectura y compresión.

Sobre escritura del método equals().

Sobre escritura del método hashCode().

Sobre escritura del método compare().

Sobre escritura del método compareTo().

10.4. Especificaciones sobre el formato del código fuente:

Tabulación:

La unidad de tabulación será de 2 espacios.

Page 36: Estándares DSI - Programación

36 Universidad Industrial de Santander UIS División de Servicios de Información

Estándares de desarrollo Java EE 5.0

Longitud de línea

Se deben evitar líneas de 80 o más caracteres ya que algunas herramientas no las manejan bien,

además que líneas demasiado extensas hacen difícil la lectura del código.

Ruptura de líneas

Cuando una expresión no cabe en una única línea, se debe romper de acuerdo a estos principios

generales:

Romper después de una coma.

Romper antes de un operador.

Preferir las rupturas de alto nivel a las de bajo nivel. (por ejemplo no romper por operador

dentro de paréntesis.

Alinear la nueva línea con el principio de la expresión al mismo nivel que la línea anterior y

dar cuatro tabulaciones.

10.5. Declaraciones y sentencias

Sentencias package e imports:

Deben seguir las siguientes reglas de formato.

Estas sentencias no van tabuladas.

Se debe declarar una por línea.

No utilizar comodines.

Variables locales:

Todas las variables locales deben inicializarse en el sitio en donde se declaran.

Las variables deben declararse al inicio de cada método y no esperar a declararlas hasta su primer

uso. La única excepción son las variables de bucles que en Java se pueden declarar dentro de la

sentencia for. Apropósito de estas variables, se utilizarán las letras de la i a la z en la medida que

se vayan necesitando.

Clases, interfaces y métodos:

En las declaraciones se deben seguir las siguientes reglas de formato:

Ningún espacio entre el nombre del método y el paréntesis "(" que abre su lista de

parámetros.

La llave de apertura "{" aparece al final de la misma línea que la sentencia de declaración.

Page 37: Estándares DSI - Programación

37 Universidad Industrial de Santander UIS División de Servicios de Información

Estándares de desarrollo Java EE 5.0

La llave de cierre "}" comienza una línea nueva tabulada para coincidir con su sentencia de

apertura correspondiente, excepto cuando es un bloque vacío que la llave de cierre "}"

debe aparecer inmediatamente después de la de apertura "{".

Los métodos están separados por una línea en blanco.

Las clases e interfaces principales no van tabuladas

Los bloques de código que pertenecen a una clase o método van tabulados.

Sentencias simples:

Se debe escribir solo una sentencia por línea, y no escribir más de una separadas por punto y

coma en la misma línea sin importar lo cortas que puedan ser.

Sentencias compuestas:

Las sentencias compuestas son sentencias que contienen una lista de sentencias encerradas entre

llaves "{" y "}" y deben seguir las siguientes reglas de formato.

Las sentencias internas deben estar tabuladas un nivel más que la sentencia compuesta.

La llave de apertura debe estar al final de la línea que comienza la sentencia compuesta; la

llave de cierre debe estar en una nueva línea y estar tabulada al nivel del principio de la

sentencia compuesta.

Las llaves se usan en todas las sentencias compuestas, incluidas las sentencias únicas,

cuando forman parte de una estructura de control, como una sentencia if-else o un bucle

for. Esto hace más fácil introducir nuevas sentencias sin provocar errores accidentales al

olvidarse añadir las llaves.

Sentencias if:

Deben seguir las reglas de las sentencias compuestas, debe existir un espacio entre la palabra

reservada if y el paréntesis de apertura de la condición y otro entre el paréntesis de cierre de la

condición y la llave de apertura del if. En general el formato que debe seguirse es el siguiente:

if (condición) {

sentencias;

}

Page 38: Estándares DSI - Programación

38 Universidad Industrial de Santander UIS División de Servicios de Información

Estándares de desarrollo Java EE 5.0

if (condición) {

sentencias;

} else {

sentencias;

}

if (condición) {

sentencias;

} else if (condición) {

sentencias;

} else {

sentencias;

}

Las sentencias if siempre llevan llaves, no importa que solo tengan una sentencia.

Sentencias for:

Estas sentencias deben seguir las reglas de las sentencias compuestas además del siguiente

formato:

for (inicialización; condición; actualización) {

sentencias;

}

Una sentencia for vacía (aquella en la que todo el trabajo se hace en las cláusulas de inicialización,

condición y actualización) debería tener el siguiente formato:

for (inicialización; condición; actualización);

Observe que se omiten las llaves de apertura y cierre

Evitar la complejidad de utilizar más de tres variables en la inicialización. En lugar de esto se deben

usar sentencias separadas antes del bucle for.

Page 39: Estándares DSI - Programación

39 Universidad Industrial de Santander UIS División de Servicios de Información

Estándares de desarrollo Java EE 5.0

Sentencias while:

Una sentencia while debe seguir el siguiente formato:

while (condición) {

sentencias;

}

Una sentencia while vacía debe tener el siguiente formato:

while (condición);

Observe que se omiten las llaves de apertura y cierre.

Sentencias do-while:

Una sentencia do-while debe tener el siguiente formato:

do {

sentencias;

} while (condición);

Sentencias switch:

Una sentencia switch debe tener el siguiente formato:

switch (condición) {

case ABC:

sentencias;

case DEF:

sentencias;

break;

case XYZ:

sentencias;

break;

default:

Page 40: Estándares DSI - Programación

40 Universidad Industrial de Santander UIS División de Servicios de Información

Estándares de desarrollo Java EE 5.0

sentencias;

break;

}

Todas las sentencias switch deberían incluir un caso por defecto. El break en el caso por defecto

es redundante, pero debe colocarse, esto puede prevenir un error de continuar con el siguiente si

más adelante se incluye otro caso.

Sentencias try-catch:

Una sentencia try-catch debe tener el siguiente formato:

try {

sentencias;

} catch (ExceptionClass e) {

sentencias;

}

Una sentencia try-catch puede venir seguida de una sentencia finally, la cual se ejecuta siempre

independientemente de que el bloque try se haya completado correctamente o no.

try {

sentencias;

} catch (ExceptionClass e) {

sentencias;

} finally {

sentencias;

}

Líneas en blanco

Las líneas en blanco mejoran la legibilidad resaltando secciones de código que están relacionadas

lógicamente.

En las siguientes circunstancias, siempre se deben usar dos líneas en blanco:

Entre secciones de un archivo de código fuente.

Entre definiciones de clases e interfaces.

Page 41: Estándares DSI - Programación

41 Universidad Industrial de Santander UIS División de Servicios de Información

Estándares de desarrollo Java EE 5.0

En las siguientes circunstancias, siempre se debería usar una línea en blanco:

Entre métodos.

Entre las variables locales de un método y su primera sentencia.

Antes de un comentario de bloque o de una sola línea.

Entre las secciones lógicas de un método, para mejorar la legibilidad.

Espacios en blanco:

Los espacios en blanco deberían usarse en las siguientes circunstancias:

Una palabra reservada seguida por un paréntesis Por ejemplo:

while (true) {

o sentencias;

}

En las listas de argumentos, debe haber un espacio después de cada coma.

Todos los operadores binarios, excepto el operador punto (.) deben estar separados de sus

operandos por espacios. Los operadores unarios (incremento ++, decremento --, negativo -

) nunca deben estar separados de sus operandos. Por ejemplo:

Las expresiones de una sentencia for deben estar separadas por espacios en blanco. Por

ejemplo:

for (expr1; expr2; expr3);

Las conversiones de tipo (cast) deberían estar seguidas de un espacio en blanco. Por

ejemplo:

variableEntera = (int) variableCadena;

10.6. Sentencias JPQL Y SQL

Dado la similitud entre las sentencias del lenguaje SQL y el JPQL, se tratarán en conjunto y no por

separado.

Sentencia SELECT

Cada una de las partes que componen una sentencia SELECT deben estar en una línea

independiente. Por ejemplo:

SELECT e

FROM estudiante e

WHERE e.nombre LIKE “%CARLOS%”

ORDER BY e.codigo

Page 42: Estándares DSI - Programación

42 Universidad Industrial de Santander UIS División de Servicios de Información

Estándares de desarrollo Java EE 5.0

Si la línea excede los 80 caracteres se sigue la convención de la estructura de líneas.

Para los SELECT anidados se empiezan con paréntesis en la línea de la condición y el

SELECT en la siguiente. El paréntesis que termina el SELECT se coloca al final de la

última sentencia. Por ejemplo:

SELECT e

FROM estudiante e

WHERE e.programa IN (

SELECT p.programa

FROM programaAcademico p

WHERE p.nombre LIKE “%SISTEMAS%” )

Las condiciones empiezan con el operador lógico. Por ejemplo:

SELECT e

FROM estudiante e

WHERE e.nombre LIKE “%CARLOS%”

and e.apellido = “GOMEZ”

and e.programa = 23

ORDER BY e.codigo

Para las condiciones agrupadas se utiliza la misma convención del operador lógico y los

paréntesis. Por ejemplo:

SELECT e

FROM estudiante e

WHERE e.nombre LIKE “%CARLOS%”

and (

e.apellido = “GOMEZ”

or e.apellido = “ARRIETA” )

ORDER BY e.codigo

Page 43: Estándares DSI - Programación

43 Universidad Industrial de Santander UIS División de Servicios de Información

Estándares de desarrollo Java EE 5.0

Sentencias INSERT, UPDATE Y DELETE (SQL)

Se deben especificar los campos que se van a insertar. Por ejemplo:

INSERT INTO estudiante (codigo, nombre)

VALUES (1,”CARLOS”)

Cada campo que se vaya a actualizar debe estar especificado en una línea independiente.

Por ejemplo:

UPDATE estudiante

SET codigo = 1,

nombre = “Oscar”,

apellido = “Suárez”

WHERE codigo = 1971950

Tablas temporales, procedimientos almacenados e índices.

Se debe seguir la siguiente estructura:

CREATE TEMP TABLE tabla (

Campo1 tipo1 constraints,

Campo2 tipo2 constraints,

campoN timpoN constraints )

Cada asignación de parámetros desde JAVA se debe hacer en una sola línea:

ps.setString(1,valor);

ps.setString(2,valor);

Para la creación de índices se debe hacer en una sola línea.

Page 44: Estándares DSI - Programación

44 Universidad Industrial de Santander UIS División de Servicios de Información

Estándares de desarrollo Java EE 5.0

11. UML

11.1. Casos de Uso

Para el desarrollo del modelo de casos de uso, se debe realizar un diagrama de casos de usos por

módulo del sistema a implementar siguiendo el estándar propuesto por el Lenguaje Unificado de

Modelado 2.1 (UML). Se deben tener en cuenta los siguientes puntos:

Identificación de Actores

Se identifican con el rol que desempeñan en el sistema.

Diagrama de Casos de Uso

El diagrama de casos de uso se tiene que realizar con la herramienta Enterprise Architect. Cada

caso de uso constituye un flujo completo de eventos especificando la interacción que toma lugar

entre el actor y el sistema.

Casos de Uso

Se deben identificar con una acción. Los verbos que se pueden utilizar se encuentran al final del

documento.

La información mínima requerida por cada caso de uso es la siguiente:

Descripción completa

Precondiciones y postcondiciones

Descripción del escenario básico y alternos

Diagrama de clases

Si el caso de uso es complejo se debe incluir:

Diagrama de secuencia y/o diagrama de actividades

Page 45: Estándares DSI - Programación

45 Universidad Industrial de Santander UIS División de Servicios de Información

Estándares de desarrollo Java EE 5.0

11.2. Diagrama de clases

Para el diagrama de clases se debe tener en cuenta:

Incluir en cada clase todos los atributos. Esto implica adicionar aquellos que son propios y

generados por las relaciones (objetos o listas) que tenga la clase.

Especificar la dirección (unidireccional o bidireccional) de la relación en el gráfico del diagrama

de clases.

Todo diagrama debe mostrar los atributos de cada una de las clases.

No incluir los métodos set y get como operaciones de la clase.

Page 46: Estándares DSI - Programación

46 Universidad Industrial de Santander UIS División de Servicios de Información

Estándares de desarrollo Java EE 5.0

12. ANEXO A: VERBOS

12.1. Lista de Verbos

A nivel de casos de uso

Consultar Consultar datos

Guardar Guardar información que no implique la relación de datos

Asignar Relacionar datos

Modificar Actualización de datos

Eliminar Borrar definitivamente información del sistema

Enviar Enviar notificación a otro usuario para continuar con el proceso

Aprobar Dar visto bueno. Se utiliza cuando el proceso es complejo, es decir, que implica

varias rutas alternas.

Cerrar Terminar un proceso el cual no podrá volver a ser modificado

Crear Insertar un registro o iniciar un proceso

Cancelar Recuperar total o parcialmente un proceso

Calcular Realizar operaciones matemáticas

Cargar Importar datos a una tabla

Finalizar Finalizar vigencia de registros

Generar Proceso que realiza N transacciones de forma automática. Ej: Generar deudas

Page 47: Estándares DSI - Programación

47 Universidad Industrial de Santander UIS División de Servicios de Información

Estándares de desarrollo Java EE 5.0

Listar Mostrar en pantalla un reporte y/o imprimirlo

Revisar Aceptar o rechazar un proceso. Insertar o actualizar un estado.

Rechazar No aprobar. Se utiliza cuando el proceso es complejo, es decir, que implica

varias rutas alternas.

Verificar Validar datos

Filtrar Filtrar los datos de una consulta por un buscador o parámetros de búsqueda

Hacer

mantenimiento

Mantenimiento de las tablas soporte (registro, actualización y borrado)

Además se pueden consultar en Enterprise Architect en la carpeta Terminología.

A nivel de métodos

Consultar Consultar datos

Guardar Guardar información. Si implica la relación de datos se puede utilizar asignar

Asignar Relacionar datos

Modificar Actualización de datos

Eliminar Borrar definitivamente información del sistema

Enviar Enviar notificación a otro usuario para continuar con el proceso

Aprobar Dar visto bueno. Se utiliza cuando el proceso es complejo, es decir, que implica

varias rutas alternas.

Cerrar Terminar un proceso el cual no podrá volver a ser modificado

Page 48: Estándares DSI - Programación

48 Universidad Industrial de Santander UIS División de Servicios de Información

Estándares de desarrollo Java EE 5.0

Crear Insertar un registro o iniciar un proceso

Cancelar Recuperar total o parcialmente un proceso

Calcular Realizar operaciones matemáticas

Cargar Importar datos a una tabla

Finalizar

vigencia

Finalizar vigencia de registros

Generar Proceso que realiza N transacciones de forma automática. Ej: Generar deudas

Listar Mostrar en pantalla un reporte y/o imprimirlo

Revisar Aceptar o rechazar un proceso. Insertar o actualizar un estado.

Rechazar No aprobar. Se utiliza cuando el proceso es complejo, es decir, que implica

varias rutas alternas.

Verificar Validar datos

Filtrar Filtrar los datos de una consulta por un buscador o parámetros de búsqueda

A nivel de interfaz de usuario

Se debe descargar el archivo messages_es_CO.properties utilizando el programa Tortoise. Allí

se encuentran las etiquetas correspondientes al nombre de los botones, mensajes, etiquetas y

errores que se deben utilizar.