Está en la página 1de 21

ANEXO a la Gua de Estndares

Normas de Codificacin

ndice
1Introduccin..............................................................4 2Juego de Caracteres...................................................4
2.1Consideraciones generales............................................4 2.2Pginas estticas HTML y dinmicas JSP........................4 2.3Ficheros XML...............................................................5 2.4Configuracin local del servidor....................................5

3Normativa del cdigo java..........................................5


3.1Convenciones de nombrado..........................................5
1.1.1Paquetes.......................................................................................... 5 1.1.2Clases.............................................................................................. 6 1.1.3Interfaces......................................................................................... 6 1.1.4Constantes.......................................................................................6 1.1.5Variables.......................................................................................... 6 1.1.6Variables locales..............................................................................7 1.1.7Parmetros......................................................................................7 1.1.8Mtodos........................................................................................... 7 1.1.9Mtodos Set y Get............................................................................7 1.1.10 Mtodos de conversin de tipos....................................................8

3.2Convenciones de documentacin...................................8
1.1.11Javadoc..........................................................................................8 1.1.12Paquetes........................................................................................8 1.1.13Clases e Interfaces.........................................................................8 1.1.14Mtodos......................................................................................... 9 1.1.15Constantes, variables de Clase y variables de Instancia...............9

3.3Normas de codificacin.................................................9
1.1.16Normas obligatorias para el despliegue. .....................................10 1.1.17Normas automticas y obligatorias .............................................11

1.1.18Normas de cdigo duplicado........................................................13 1.1.19Normas comprobadas por mtrica...............................................14 1.1.20Normas manuales........................................................................17

3.4Gestin de errores y ficheros de traza de la aplicacin. 18

4Normativa de servicios web......................................20


4.1Interface del servicio web ..........................................20
1.1.21Cabeceras WSDL..........................................................................20 1.1.22Inline WSDL..................................................................................21 1.1.23Namespaces ................................................................................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 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
G DoNotCallGarbageCollectionExplicitly No llamar explcitamente al recolector de basura.

Descripcin

Comprobar
PMD

Umbral

UncommentedMain

No se deben incluir mtodos main en el cdigo de la aplicacin.

Checkstyle

No se deben usar en el cdigo las siguientes instrucciones. RegExp System.setProperties System.exit System.err System.out setMaxInactiveInterval

Checkstyle

R RegExp

No se deben usar en el cdigo las siguientes instrucciones. Thread.sleep

Checkstyle

R UnnecessaryCaseChange

Usar equalsIgnoreCase() en lugar de toLowerCase() / toUpperCase().equals para comparar cadenas String.

PMD

R SuppressWarnings

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

Checkstyle

10

usoSingleThreadModel

No se permite el uso del paquete: javax.servlet.SingleThreadModel

PMD

G 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.

PMD.

M SimpleDateFormatNeedsLocale

Se debe desacoplar el cdigo de la configuracin concreta del servidor. Cuando se cree una instancia de SimpleDateFormat se debe especificar el locale.

PMD

M NumberFormatSinLocale

Se debe desacoplar el cdigo de la configuracin concreta del servidor. Cuando se cree una instancia de NumberFormat se debe especificar el locale.

PMD

1.1.17

Normas automticas y obligatorias


comprobar

Consideramos las siguientes normas que se pueden automticamente a nivel individual y son de obligado cumplimiento.

El umbral indica si alguna regla PMD o Checkstyle no puede superar un valor mnimo establecido. Norma Descripcin
No asignar valores inseguros a variables o propiedades estticas. AssignmentToNonFinalStatic

Comprobar
PMD

Umbral

AvoidCatchingNPE

No capturar excepciones NullPointerException.

PMD

AvoidPrintStackTrace

No se permite el uso de llamadas ex.printStackTrace().

PMD

AvoidThrowingNullPointerException

No disparar excepciones NullPointerException.

PMD

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

25

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.

PMD.

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

ExcessivePublicCount

El nmero mximo de mtodos y atributos pblicos declarados en una clase.

PMD

60

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).

Checkstyle

No se permite el uso del paquete: IllegalImport sun.*

Checkstyle

No est permitido el uso de la clase: usoNativeJdbcExtractor org.springframework.jdbc.support.nativej dbc.NativeJdbcExtractor.

PMD

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: RegExp System.in

Checkstyle

SignatureDeclareThrowsException

No usar throws Exception en la declaracin del mtodo, usar una clase derivada de RuntimeException o una excepcin chequeada.

PMD

No se permite llamadas SystemPrintln System.out .print System.err.print

PMD

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
AbstractNaming

Descripcin
Los nombres de las clases abstractas deben empezar por AbstractXXX.

Comprobar
PMD

Umbral

AvoidDuplicateLiterals

Evitar literales duplicados, declarar el String como campo constante.

PMD

AvoidStarImpor

No se permite usar * en las declaraciones import.

Checkstyle

AvoidUsingOctalValues

Al expresar valores decimales, no escribir ceros precedentes, ya que son tomados como valores octales.

PMD

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

14

EqualsNull

No usar equals() para comparar con null.

PMD

FallThrough

Todas las sentencias de un switch deben tener su sentencia de cierre (break, return, throw o continue).

Checkstyle

Una sentencia for esta siempre bien formada. No estar bien formado tiene la parte de inicializacin, la expresin de salida y la de actualizacin. ForBienFormado Son validos los foreach. Ejemplo: for (int i=0;i<10;i++); for(String campo: ColecionString);

PMD

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. 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.

Checkstyle

JavadocStyle

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

PMD

30

15

parmetros debe ser inferior a 30.

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

200

OperatorWrap

Las sentencias con operadores deben estar expresadas de manera clara (parntesis, espacios,).

Checkstyle

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. 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)

PMD

son variables correctas.

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..

PMD

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

16

UnusedImports

Comprueba que no existan declaraciones import sin usar.

Checkstyle

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. VariableNamingConventions Las variables finales deben estar en maysculas. Las variables no finales no deben tener el smbolo _

PMD

VisibilityModifier

Slo pueden ser pblicos, los campos de tipo static final

Checkstyle

1.1.20

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. 17

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 java.io.OutputStream, subclases de java.io.Reader y subclases de java.io.Writer). 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. 18

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 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 19

404: indica que la peticin solicitada no est disponible (posiblemente por no corresponderse con ninguna accin programada en la aplicacin) 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>

20

1.1.22

Inline WSDL

Utilizar inline WSDLs siempre que sea posible. No utilizar "include" 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