Está en la página 1de 21

ANEXO a la Gua de

Estndares
Normas de Codificacin

ndice
1 Introduccin______________________________________________4
2 Juego de Caracteres______________________________________4
2.1

Consideraciones generales________________________________4

2.2

Pginas estticas HTML y dinmicas JSP_________________4

2.3

Ficheros XML_______________________________________________5

2.4

Configuracin local del servidor___________________________5

3 Normativa del cdigo java_______________________________5


3.1

Convenciones de nombrado_______________________________5

3.1.1

Paquetes_________________________________________________________5

3.1.2

Clases____________________________________________________________6

3.1.3

Interfaces________________________________________________________6

3.1.4

Constantes_______________________________________________________6

3.1.5

Variables_________________________________________________________6

3.1.6

Variables locales_________________________________________________7

3.1.7

Parmetros_______________________________________________________7

3.1.8

Mtodos__________________________________________________________7

3.1.9

Mtodos Set y Get________________________________________________7

3.1.10

Mtodos de conversin de tipos_________________________________7

3.2

Convenciones de documentacin_________________________8

3.2.1

Javadoc__________________________________________________________8

3.2.2

Paquetes_________________________________________________________8

3.2.3

Clases e Interfaces_______________________________________________8

3.2.4

Mtodos__________________________________________________________8

3.2.5

Constantes, variables de Clase y variables de Instancia__________9

3.3

Normas de codificacin____________________________________9

3.3.1

Normas obligatorias para el despliegue._________________________10

3.3.2

Normas automticas y obligatorias______________________________11

3.3.3

Normas de cdigo duplicado____________________________________13

3.3.4

Normas comprobadas por mtrica_______________________________14

3.3.5

Normas manuales_______________________________________________17

3.4

Gestin de errores y ficheros de traza de la aplicacin


18

4 Normativa de servicios web____________________________20


4.1

Interface del servicio web________________________________20

4.1.1

Cabeceras WSDL________________________________________________20

4.1.2

Inline WSDL_____________________________________________________21

4.1.3

Namespaces____________________________________________________21

1 Introduccin
El siguiente documento contiene las recomendaciones y la normativa de
calidad que debe cumplir el cdigo fuente de las aplicaciones.
Estas normas son de obligado cumplimiento aunque podrn considerarse
excepciones, que sern propuestas por el equipo y analizadas conjuntamente con el
Comit de Estndares.
Durante el control de calidad se realizar una comprobacin lo ms automtica
posible que permita generar un informe de cumplimiento de la normativa as como una
mtrica de calidad asociada.
Las herramientas de anlisis esttico del cdigo son gratuitas y de libre
distribucin. Esto implica que cada proveedor puede realizar tambin dicha
comprobacin antes de realizar la entrega usando el conjunto de reglas
proporcionadas por el IAM.

2 Juego de Caracteres
2.1 Consideraciones generales
Para evitar problemas por el uso de distintas configuraciones en los ficheros de
cdigo fuente java, los ficheros de configuracin, los ficheros de recursos de idiomas y
scripts de base de datos deben estar codificadas en UTF-8, tanto para ficheros Java,
pginas HTML, JSP, scripts de base de datos, etc.

2.2 Pginas estticas HTML y dinmicas JSP


Los parmetros de la peticin usarn el mismo juego de caracteres que el
formulario, por lo que conviene hacer una declaracin explcita del juego de
caracteres:
Esto generar la etiqueta META en la pgina HTML con la indicacin del
charset=UTF-8
<META http-equiv="Content-Type" content="text/html; charset=UTF-8">

- En una JSP, la directiva de pgina contentType puede ser utilizada con este
mismo fin:
<%@ page language="java" contentType="text/html; charset=UTF-8"%>

2.3 Ficheros XML


Los ficheros XML deben estar codificados en UTF-8, de modo que deben de
comenzar siempre por:
<?xml version="1.0" encoding="UTF-8"?>

2.4 Configuracin local del servidor


Al realizar la codificacin de un proyecto, se debe independizar el tratamiento
de nmeros, fechas, de la configuracin local del servidor.
Para ello se deben usar siempre que sea posible los mtodos de las clases de
manipulacin de fechas y nmeros que soporten el paso de un objeto de tipo Locale.
Por ejemplo usar el constructor SimpleDateFormat (String dateFormat, Locale locale)
o el mtodo NumberFormat.getInstance(Locale locale).

3 Normativa del cdigo java


3.1 Convenciones de nombrado
Las convenciones de nombrado permiten que las aplicaciones desarrolladas
sean ms fciles de leer y de mantener, adems de un punto de partida para la calidad
de aplicaciones.
De modo general se siguen los criterios de nombrado definidos en la web de
Oracle: http://www.oracle.com/technetwork/java/codeconvtoc-136057.html. A partir de
estos criterios se recomienda seguir la siguiente nomenclatura para los distintos
elementos java.
1.1.1

Paquetes

Los nombres de paquetes deben estar en minsculas.

Evitar tener ms de 7 niveles de paquetes.

Usar nombres descriptivos de menos de 15 caracteres.

Los nombres de paquete son de la forma es.iam.[proyecto].[funcionalidad].


[capa].* donde el significado es:
o

[proyecto] ser el acrnimo de proyecto de 5 letras.

[funcionalidad] se refiere a la aplicacin, proceso de negocio o caso


de uso que implementa.
5

[capa] indica la capa o servicio de la arquitectura donde se localiza la


clase o interface. (view, business, persistence, service).

Este criterio es opcional para paquetes ya existentes.

Los paquetes que contienen las excepciones de una determinada capa sern
de la forma es.iam.[proyecto].[funcionalidad].[capa].*.exception

1.1.2

Clases

El nombre de la clase debe empezar por mayscula seguido de minsculas.

Los nombres de las clases deben ser simples y describir la funcionalidad


proporcionada.

Utilizar nombres significativos y completos; evitar utilizar acrnimos y


abreviaturas.

Si la clase tiene un nombre compuesto, utilizar una combinacin minscula /


mayscula para cada nombre, en lugar del carcter _ (Ej.: GestorArchivos en
lugar de Gestor_Archivos o Gestor _ archivos).

Las clases de Excepciones terminarn siempre en Exception. (Ej.:


FicheroNoEncontradoException)

1.1.3

Interfaces

Los nombres de las interfaces siguen las mismas reglas que los nombres de
las clases.

Los nombres de las interfaces deben empezar por la letra I mayscula para
distinguir Clases e Interfaces.

1.1.4

Constantes

Los identificadores de constantes deben ser descriptivos y todos en mayscula.

Para nombres compuestos usamos nombres en maysculas separados por _.


(EJ.:IMPUESTO_SOCIEDADES)

1.1.5

Variables

Los identificadores de variable deben empezar por minscula y no deben


comenzar por _ o $.

Para nombres compuestos, utilizar una combinacin mayscula / minscula en


lugar del carcter _. (EJ.: identificadorCiudadano en lugar de
idenficador_ciudadano)

1.1.6

Variables locales

Los identificadores de variables locales deben ser significativos. Se pueden


usar nombres cortos de una letra para variables temporales de usar y tirar:

i, j, k, n, m para tipos enteros.

c, d, e para tipos carcter.

1.1.7

Parmetros

Los identificadores de parmetros de mtodos deben seguir las mismas


normas que las variables.

1.1.8

Mtodos

Los nombres de mtodos deben comenzar con una letra minscula.

Para identificadores compuestos, utiliza una combinacin mayscula /


minscula en lugar del carcter _ (Ej. generaInforme)

El nombre del mtodo no debe superar los 30 caracteres de longitud.

1.1.9

Mtodos Set y Get

Son los mtodos que se utilizan para encapsular el acceso a una variable de la
clase que debe ser privada. Estos mtodos se denominan igual que la variable de la
clase que encapsulan, con la salvedad de que se substituye el prefijo de la variable por
los siguientes prefijos:

set para el setter, es decir, para el mtodo que asigna un valor a la


propiedad de la clase.

is para el getter de una propiedad booleana, es decir, para el mtodo


que devuelve el valor de una propiedad booleana de la clase.

get para el getter de una variable no booleana de la clase.

1.1.10

Mtodos de conversin de tipos

Si la clase dispone de un mtodo de conversin a otro tipo, denominarlo con el


prefijo to seguido del nombre del tipo, de forma anloga a como hace API de JAVA
con el mtodo toString(). (EJ.:toXML())

3.2 Convenciones de documentacin


1.1.11

Javadoc

La herramienta Javadoc genera documentacin en formato HTML a partir de


los comentarios de tipo Javadoc.
Se debe utilizar este tipo de comentarios para ir documentando el cdigo segn
se genera o revisa. Utilizar las siguientes etiquetas HTML para mejorar la legibilidad de
los comentarios:

<p> para separar prrafos.

<code> ... </code> o <tt> ... </tt> para fragmentos pequeos de cdigo.

<pre> ... </pre> para fragmentos largos de cdigo.


Se seguirn las siguientes normas para documentar el cdigo java:

Se debe tener documentado todo el API que exporta tu clase, es decir, las
variables, constantes, mtodos y constructores public y protected.

Utilizar comentarios Javadoc para explicar qu hace la clase, o mtodo, para


qu sirve una interface, cul es el propsito de una variable o constante. Es
recomendable no indicar el cmo lo hace ya que es fcil que el comentario se
quede desactualizado.

1.1.12

Paquetes

Incluir en cada directorio un fichero package.html o package-info.java en el que


documente el propsito del paquete.
1.1.13

Clases e Interfaces

Incluir antes de la declaracin de cada clase o interface una descripcin del


mismo en formato Javadoc
Finalizar la descripcin con las etiquetas siguientes:

@author - para indicar el autor o autores.

1.1.14

Mtodos

Al documentar un mtodo se establece un contrato entre el que desarrolla la


clase o interface y quien vaya a usarlo.
En este contrato se debe especificar lo que se espera de los parmetros de
entrada, las acciones que se comprometen a realizar y las excepciones que se van a
lanzar si el cliente no cumple su parte del contrato o si se produce un error durante la
ejecucin.
Utilizar comentarios Javadoc para documentar este contrato:

Propsito del mtodo.

Parmetros del mtodo. Utilizar la etiqueta @param de Javadoc. En caso de


restricciones en los parmetros indicarlo aqu. (Ej.: El valor no puede ser nulo)

Valor de retorno, si aplica. Utilizar la etiqueta @return de Javadoc.

Excepciones que puede lanzar el mtodo. Utilizar la etiqueta @throws de


Javadoc. Explicar las situaciones dnde producir estas excepciones y
documentar todas las excepciones que puede lanzar el mtodo.

1.1.15

Constantes, variables de Clase y


Instancia

variables de

Utilizar comentarios Javadoc para documentar como mnimo las constantes,


variables de clase y variables de instancia que exporta la clase (public y protected).

3.3 Normas de codificacin


A continuacin tenemos la siguiente tabla con una relacin de las normas de
obligado cumplimiento para el cdigo fuente java de todas las aplicaciones.
Se usarn las herramientas PMD (http://pmd.sourceforge.net) y Checkstyle
(http://checkstyle.sourceforge.net/) para el anlisis esttico y automtico del cdigo.
Las normas pueden comprobarse en RSA instalando los plugin necesarios.
Con maven se pueden comprobar configurando de forma correcta la seccin de
reporting del pom.
Para comprobar las normas con maven se deben ejecutar los siguientes
comandos.
mvn site
mvn site:deploy

Tras esto se debe acceder a la carpeta donde se ha configurado la generacin


de la documentacin abrir el archivo index.html y comprobar el reporting de todos los
mdulos del proyecto.
1.1.16

Normas obligatorias para el despliegue.

Estas normas se comprobaran de forma automtica sobre el cdigo y son de


obligado cumplimiento si se solicita un despliegue. En caso de existir un
incumplimiento en estas reglas se parar la solicitud de despliegue.
Norma

Descripcin

Comprobar

Umbral

PMD
DoNotCallGarbageCollectionExplicitly

No llamar explcitamente al recolector


de basura.

UncommentedMain

No se deben incluir mtodos main en


el cdigo de la aplicacin.

Checkstyle

No se deben usar en el cdigo las


siguientes instrucciones.

Checkstyle

RegExp

R
RegExp

System.setProperties

System.exit

System.err

System.out

setMaxInactiveInterval

No se deben usar en el cdigo las


siguientes instrucciones.

Checkstyle

Thread.sleep

PMD

UnnecessaryCaseChange

Usar equalsIgnoreCase() en lugar de


toLowerCase() /
toUpperCase().equals para comparar
cadenas String.

No usar la anotacin
@SuppressWarnings para evitar los
warnings del compilador

Checkstyle

SuppressWarnings

10

usoSingleThreadModel

G
DoNotUseThreads

M
SimpleDateFormatNeedsLocale

No se permite el uso del paquete:


javax.servlet.SingleThreadModel

PMD

No crear threads propios desde el


cdigo. No tienen accesos a los
recursos y contexto J2EE. No son
controlables por el servidor de
aplicaciones. Usar
AsynchronousBeans o JMS para la
programacin de procesos
asncronos.

PMD.

Se debe desacoplar el cdigo de la


configuracin concreta del servidor.

PMD

Cuando se cree una instancia de


SimpleDateFormat se debe
especificar el locale.

Se debe desacoplar el cdigo de la


configuracin concreta del servidor.
NumberFormatSinLocale

1.1.17

PMD

Cuando se cree una instancia de


NumberFormat se debe especificar el
locale.

Normas automticas y obligatorias

Consideramos las siguientes normas que se pueden


automticamente a nivel individual y son de obligado cumplimiento.

comprobar

El umbral indica si alguna regla PMD o Checkstyle no puede superar un valor


mnimo establecido.
Norma

Descripcin

Comprobar

No asignar valores inseguros a variables


o propiedades estticas.

PMD

AvoidCatchingNPE

No capturar excepciones
NullPointerException.

PMD

AvoidPrintStackTrace

No se permite el uso de llamadas


ex.printStackTrace().

PMD

AvoidThrowingNullPointerException

No disparar excepciones
NullPointerException.

PMD

Umbral

AssignmentToNonFinalStatic

11

AvoidThrowingRawExceptionTypes

No disparar excepciones primarias, en su


lugar lanzar subclases de ellas.

PMD

BooleanExpressionComplexity

El mximo de operadores booleanos


(&&, || y ^) permitidos.

Checkstyle

ClassNamingConventions

Los nombres de las clases deben


empezar por letra mayscula.

PMD

ConstructorCallsOverridableMethod

Los constructores no deben llamar a


mtodos sobrescritos.

PMD

CyclomaticComplexity

La complejidad ciclomtica de cada


mtodo.

PMD

PMD.

DoNotUseThreads

No crear threads propios desde el


cdigo. No tienen accesos a los recursos
y contexto J2EE. No son controlables por
el servidor de aplicaciones. Usar
AsynchronousBeans o JMS para la
programacin de procesos asncronos.

ExcessiveClassLength

El nmero mximo de lneas una clase.

PMD

2000

ExcessiveMethodLength

El nmero mximo de lneas permitidas


por mtodo.

PMD

200

ExcessiveParameterList

El nmero mximo de parmetros


permitidos en un mtodo.

PMD

14

El nmero mximo de mtodos y


atributos pblicos declarados en una
clase.

PMD

60

ExcessivePublicCount

Checkstyle

ExplicitInitialization

No se debe inicializar un campo al valor


por defecto de su tipo (nulo para
referencias u objetos, 0 para nmeros y
char, y false para bolean, etc).

No se permite el uso del paquete:

Checkstyle

25

IllegalImport

sun.*

No est permitido el uso de la clase:


usoNativeJdbcExtractor

PMD

org.springframework.jdbc.support.nativej
dbc.NativeJdbcExtractor.

12

MethodNamingConventions

Los nombres de mtodos deben


empezar siempre por letra minscula.

PMD

NoScriptlets

No se permite el uso de scriptlets en las


pginas JSP.

PMD

PackageDeclaration

Todas las clases tienen una declaracin


de paquete.

Checkstyle

PackageName

Los paquetes deben llamarse de la


forma es.iam.[proyecto].

Checkstyle

No se permiten llamadas del tipo:

Checkstyle

RegExp

SignatureDeclareThrowsException

SystemPrintln

System.in

No usar throws Exception en la


declaracin del mtodo, usar una clase
derivada de RuntimeException o una
excepcin chequeada.

PMD

No se permite llamadas

PMD

System.out .print

System.err.print

UnusedPrivateMethod

No se permiten mtodos privados


declarados sin usar.

PMD

UseArrayListInsteadOfVector

No usar la coleccin Vector. En su lugar


usar ArrayList.

PMD

UseStringBufferForStringAppends

Usar StringBuffer y el mtodo append()


en lugar de += para concatenar cadenas.

PMD

1.1.18

Normas de cdigo duplicado

Se auditar el cdigo de forma automtica para limitar el uso de cdigo


duplicado.
La herramienta a usar ser el modulo CPD asociado con la librera PMD y
tomando como base mnima de duplicacin aproximada de 5 lneas de cdigo fuente
(100 tokens).
La existencia de bloques de cdigo duplicado que superen este lmite impuesto
supondr un error que deber ser solucionado para poder realizar la aceptacin del
cdigo entregado.
13

1.1.19

Normas comprobadas por mtrica

Se consideran aqu las normas que no siendo de obligado cumplimiento a nivel


individual se comprueban automticamente por volumen a nivel de aplicacin.
El clculo se realiza con la siguiente frmula:
Porcentaje= Nmero total de violaciones/(Nmero de lneas de cdigo *100)
Solo se permitir un incumplimiento del 30% respecto a estas normas.
Norma

Descripcin

Comprobar

AbstractNaming

Los nombres de las clases abstractas


deben empezar por AbstractXXX.

PMD

AvoidDuplicateLiterals

Evitar literales duplicados, declarar el


String como campo constante.

PMD

AvoidStarImpor

No se permite usar * en las declaraciones


import.

Checkstyle

Al expresar valores decimales, no escribir


ceros precedentes, ya que son tomados
como valores octales.

PMD

AvoidUsingOctalValues

CompareObjectsWithEquals

Comparar objetos con equals, no con ==.

PMD

ConstantName

Las constantes deben ser expresadas con


todas las letras en maysculas.

Checkstyle

EmptyCatchBlock

No se permiten bloques catch vacos.

PMD

EmptyFinallyBlock

No se permiten bloques finally vacos.

PMD

EmptyIfStmt

No se permiten sentencias if sin


contenido.

PMD

EmptyStatementNotInLoop

No se permiten sentencias vacas excepto


en bucles.

PMD

EmptySwitchStatements

No se permiten bloques switch vacas.

PMD

EmptyTryBlock

No se permiten bloques try vacos.

PMD

EmptyWhileStmt

No se permiten sentencias while sin


contenido.

PMD

Umbral

14

EqualsNull

No usar equals() para comparar con null.

PMD

Todas las sentencias de un switch deben


tener su sentencia de cierre (break,
return, throw o continue).

Checkstyle

FallThrough

Una sentencia for esta siempre bien


formada. No estar bien formado tiene la
parte de inicializacin, la expresin de
salida y la de actualizacin.

PMD

ForBienFormado

Son validos los foreach.


Ejemplo:
for (int i=0;i<10;i++);
for(String campo: ColecionString);

InstantiationToGetClass

No instanciar un objeto para llamar a


getClass(), usar .class en su lugar.

PMD

JavadocPackage

Todos los paquetes deben llevar


documentacin de paquete.

Checkstyle

Valida los comentarios Javadoc para


asegurarse de que estn bien formado.

Checkstyle

JavadocStyle

Se asegura de que la primera


sentencia termina en punto .
Interrogacin ? o exclamacin
!
Chequea que todo el texto
necesario para el javadoc no
est vaco.
Cheque el texto por tags HTML
incompletas.
Cheque que la documentacin
de paquete est bien formada.

JavadocVariable

Comprueba que todas las variables tienen


su javadoc correspondiente.

Checkstyle

JavadocType

Comprueba que todas las clases tienen


su javadoc correspondiente.

Checkstyle

JavadocMethod

Comprueba que todas los mtodos tienen


su javadoc correspondiente.

Checkstyle

LongVariable

La longitud del nombre de variables o


parmetros debe ser inferior a 30.

PMD

30

15

MissingBreakInSwitch

Debe haber al menos una sentencia


break en cada sentencia case de switch.

PMD

NPathComplexity

Nmero mximo de caminos acclicos que


puede ejecutar un mtodo.

PMD

Las sentencias con operadores deben


estar expresadas de manera clara
(parntesis, espacios,).

Checkstyle

OperatorWrap

PositionLiteralsFirstInComparison
s

Al hacer comparaciones de cadenas,


posicionar siempre primero el literal para
evitar NullPointerException.

PMD

RedundantImport

Comprueba que no existan declaraciones


import duplicadas.

Checkstyle

ShortMethodName

Comprueba nombres demasiado cortos


de mtodos.

PMD

Comprueba nombres demasiado cortos


de variables o parmetros.

PMD

200

No tiene en cuenta las variables


declaradas dentro de inicializacin de un
bucle for ni las declaradas en un catch.
ShortVariable
Por ejemplo:

for (int i=0;i<10;i++)


catch(UnaExcepcion e)

son variables correctas.

PMD

StringBufferInstantiationWithChar

Evitar instanciar StringBuffer con un char


ya que el char ser convertido a un entero
y tomado por el constructor como tamao
del StringBuffer..

StringToString

No llamar a .toString() desde un objeto


String.

PMD

UnconditionalIfStatement

No se permiten sentencias if que siempre


son verdaderas o falsas.

PMD

UnusedFormalParameter

No se permiten parmetros de mtodos o


constructores que luego no se utilicen.

PMD

UnusedImports

Comprueba que no existan declaraciones


import sin usar.

Checkstyle

16

UnusedLocalVariable

No se permiten variables locales


declaradas sin usar.

PMD

UnusedPrivateField

No se permiten campos privados


declarados sin usar.

PMD

Los nombres de variables deben cumplir


las convenciones de nombrado.

PMD

VariableNamingConventions

VisibilityModifier

1.1.20

Las variables finales deben


estar en maysculas.
Las variables no finales no
deben tener el smbolo _

Slo pueden ser pblicos, los campos de


tipo static final

Checkstyle

Normas manuales

Consideramos las siguientes normas obligatorias pero se deben comprobar


manualmente.

Los tamaos de los objetos de sesin (HttpSession) se han de mantener


pequeos (no superiores a 5KB). Objetos muy grandes penalizan el
rendimiento por la serializacin/deserializacin. Adems consumen muchos
recursos de memoria, y de ancho de banda si se utiliza la persistencia por
replicacin de memoria entre servidores.

No utilizar el atributo isThreadSafe en las JSP, por defecto su valor es false. El


uso de este atributo con valor true implica que el servlet podra utilizar
SingleThreadModel.

La tecnologa XML/XSLT es bastante pesada de procesar para los servidores,


por lo que no se recomienda en aplicaciones de mucha carga. Usarla slo
cuando realmente haya mltiples tipos de presentacin a soportar (diferentes
tipos de dispositivo cliente).

No crear objetos de sesin HttpSession en las pginas JSP.

No crear threads propios desde el cdigo. No tienen accesos a los recursos y


contexto J2EE. No son controlables por el servidor de aplicaciones. Usar
Asynchronous Beans o JMS para la programacin de procesos asncronos.

Usar las clases BufferedInputStream, BufferedOutpuStream, BufferedReader y


BufferedWriter como recubrimiento al resto de clases de acceso a fichero del
paquete java.io. (subclases de java.io.InputStream, subclases de
17

java.io.OutputStream,
java.io.Writer).

subclases

de

java.io.Reader

subclases

de

Evitar la utilizacin de la sincronizacin, excepto en casos imprescindibles,


tanto por cdigo java utilizando synchronized como en las clases sincronizadas
del JDK, usando en su lugar la alternativa no sincronizada.

3.4 Gestin de errores y ficheros de traza de la


aplicacin
Todas las aplicaciones deben tener implementada la gestin de las
excepciones con un procedimiento de traza que permita en caso de problemas
investigar que es lo que est pasando en la aplicacin. Todas las posibles
excepciones deben de ser capturadas por la aplicacin. En el caso de que no se
capture una excepcin afecta a la ejecucin del aplicativo y al rendimiento del servidor
puesto que dicha excepcin es capturada por el servidor de aplicaciones y mostrada
en los ficheros de logs del servidor.
Todas las libreras de terceros utilizadas por la aplicacin deben igualmente
cumplir estos requisitos.
En general, ante cualquier excepcin se debe realizar un procedimiento de
recuperacin y volcar en un fichero de traza propio del aplicativo la informacin
sobre la clase/mtodo donde se ha producido el fallo y el cdigo de la excepcin,
as como la fecha y hora. Para casos en que las excepciones no sean capturadas
por la aplicacin, y teniendo en cuenta que el servidor puede ser compartido por ms
de una aplicacin en ejecucin, se recomienda que los nombres de paquetes
utilizados contengan el contexto del mdulo para poder relacionar excepciones con
aplicaciones.
Al estar desplegadas las aplicaciones en una arquitectura en cluster, adems
se deber tener en cuenta que son mltiples y dinmicos los servidores donde est
ejecutndose la aplicacin, por lo que sern mltiples los ficheros de traza a consultar
Se recomienda el uso de la librera log4j que permitir utilizar diferentes
appenders y definir el nivel de traza, tamao y formato de la traza. El fichero de
configuracin no se empaqueta en el .ear, sino que se entrega como fichero de
propiedades externo, ya que la arquitectura en cluster permitir reiniciar con las
modificaciones del mismo sin necesidad de detener completamente el servicio y sin
necesidad de desplegar el .ear. Es decir, permitir minimizar parada de servicio en
caso de necesidad de obtener mayor informacin sobre el procesamiento que est
causando el fallo, pudiendo activar la salida a un fichero propio de la aplicacin donde
se vuelquen trazas a nivel INFO o DEBUG.
Por otra parte, la generacin de trazas es un punto de bloqueo para la
aplicacin, por lo que slo se debe usar niveles de traza INFO o DEBUG en casos
estrictamente necesarios. La gestin de ficheros de traza de dichos niveles debern
18

ubicarse en un recurso NAS gestionado por el Dpto. de Desarrollo, por lo que se


aconseja establecer alguna poltica de borrados si se utiliza dicho nivel de traza;
aconsejamos en ese caso el uso de un appender de tipo RollingFileAppender que
limite nmero y tamao de los ficheros de logs.
A continuacin indicamos diversas consideraciones a tener en cuenta en la
generacin de trazas:

No
se
debe
usar
System.out,
System.err
o
exception.printStackTrace, pues dichas salidas se vuelcan
directamente en los ficheros de traza del servidor sin poder configurar
en caliente el nivel de raza. Esto podra degenerar en el
desbordamiento de dicho fichero o la lentitud del servicio.

Siempre debe entregarse un fichero de configuracin de las trazas de la


aplicacin. El fichero de configuracin se debe ubicar externo al EAR.

No se puede utilizar un appender de tipo Console para el volcado de


trazas, sino un appender de tipo RollingFile.

El nivel de traza en los entornos de Preproduccin y Produccin se


establecer siempre a ERROR para el fichero de traza almacenado en
el NAS de plataforma WAS. (Este fichero ser accesible en modo
lectura por los responsables IAM del proyecto.) El tamao total de los
ficheros de trazas no debe de superar el tamao mximo pedido en el
entorno de ejecucin, por lo que los ficheros resultantes deben de
utilizar el sistema RollingFile que permite limitarlo.

Para generacin de un fichero en nivel INFO o DEBUG o con


appender de tipo DailyRollingFile, se podr configurar el appender
para ubicar el fichero de traza en un recurso NAS gestionado por el
Dpto. de Desarrollo.

Obsrvese la importancia de diferenciar el servidor de origen en el nombre


del fichero pues podra darse un conflicto de concurrencia en la arquitectura en cluster.
Por otra parte, cuando se produzca un error en la ejecucin deber servirse
una pgina de propia de la aplicacin que oculte al usuario final la excepcin JAVA
pero le informe de la existencia de un problema en la ejecucin de su peticin. Para
ello, debe especificarse en el descriptor web.xml el mapeo entre los cdigos de error y
dichas pginas. Algunos de los cdigos de error comunes que deben incluirse en el
mapeo son:

401: indica que la peticin solicitada requiere autenticacin

404: indica que la peticin solicitada no est disponible (posiblemente


por no corresponderse con ninguna accin programada en la aplicacin)
19

500: indica que ha ocurrido un error que impide servir correctamente la


respuesta

503: indica que el servidor est temporalmente sobrecargado

4 Normativa de servicios web


El proveedor del servicio web proporciona un fichero WSDL que contiene la
descripcin del interface del servicio para la aplicacin que acta como consumidor del
mismo.

4.1 Interface del servicio web


Consideramos las siguientes normas que debe cumplir el fichero WSDL que
describe la funcionalidad del servicio web.
1.1.21

Cabeceras WSDL

El elemento <wsdl:definitions> del fichero WSDL del servicio web ser de la


forma:

<wsdl:definitions name="NombreServicio"
targetNamespace=http://ws.iam.es/nombreServicio
xmlns="http://schemas.xmlsoap.org/wsdl/"
xmlns:soap=http://schemas.xmlsoap.org/wsdl/soap/
xmlns:tns="http://ws.iam.es/nombreServicio"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
xmlns:xsd=http://www.w3.org/2001/XMLSchema>

1.1.22

Inline WSDL

Utilizar inline WSDLs siempre que sea posible. No utilizar "include"

20

El uso de sentencias include en WSDLs puede suponer problemas para


algunas herramientas de diferentes fabricantes. Con el fin de eliminar este riesgo, se
recomienda definir los esquemas en el propio XML del WSDL, sin utilizar la sentencia
include, siempre que ello sea posible.
1.1.23

Namespaces

El WSDLs del servicio web siempre tiene asignado un espacio de nombres


(namespaces).
El atributo targetNamespace del elemento <wsdl:definition> debe ser de la
forma http://ws.iam.es/servicio donde servicio es el identificador asignado al servicio.

21