Download Convenciones de Nombre en la definición de documentos XSD

Lineamientos, estándares y convenciones para la creación de Documentos XSD y WSDL
Estándares y recomendaciones para el manejo de errores de Servicios Web
LINEAMIENTOS, ESTÁNDARES Y CONVENCIONES
PARA LA CREACIÓN DE DOCUMENTOS XSD y WSDL
ESTÁNDARES Y RECOMENDACIONES PARA EL MANEJO DE ERRORES
DE SERVICIOS WEB
PROYECTO DE INTEROPERABILIDAD LIBRE ORIENTADA A SERVICIOS
PARA EL ESTADO VENEZOLANO
Nombre del Documento
Versión del documento
Fecha
Dirigido a
XSD-WSDL.odt
2.0
16 de Junio 2009
Integrantes del Proyecto Interoperabilidad Libre
Orientada a Servicios para el Estado Venezolano
Este documento define lineamientos generales, estándares y convenciones acordadas para la
creación de documentos XSD y WSDL y los estándares y recomendaciones para el manejo de
errores de servicios Web en el proyecto de Interoperabilidad Libre Orientada a Servicios para el
Estado Venezolano.
Aprobación
Autor
Revisión
Revisión
Aprobación
Aprobación
Javier Santana
Willie Nieto
Victor Liendo
Julio Cejas
Elizabeth Sierraalta
16/06/2009
Pág. 1
Lineamientos, estándares y convenciones para la creación de Documentos XSD y WSDL
Estándares y recomendaciones para el manejo de errores de Servicios Web
Lineamientos generales para la creación de documentos XSD:
1. Todo elemento XML global definido en un documento XSD debe representar
una entidad del modelo.
2. Crear un archivo XSD por cada elemento XML a definir, esto con el objetivo de
reutilizar. Utilizar el elemento import para reutilizar definiciones de elementos XML
presentes en otros documentos XSD.
3. Todo elemento XML a definir debe pertenecer a un Name Space (targetNamespace).
4. Definir el atributo elementFormDefault="qualified"en el elemento schema de
todo documento XSD.
5. Utilizar el enfoque Venedetian Blinds Style1 para definición de elementos
XML: utilizar un tipo complejo (complexType) por cada elemento XML
global definido.
6. Se recomienda una filosofía Bottom-Up para el diseño de los XSD de forma de iniciar el
diseño en los tipos de datos más sencillos y mediante composición se definen los más
complejos. Esta filosofía promoverá la organización y reutilización.
7. Para cada documento XSD debería definirse un elemento documentación que permita
describir el tipo complejo y opcionalmente a nivel de los atributos dependiendo de la
complejidad de su nombre.
Convenciones y Estándares para la creación de XSD:
Nombre de Elemento XML
para
definición
de
Entidades (ComplexType,
SimpleType y elementos
globales)
Utilizar nombres representativos empleando las mismas
convenciones de código Java para la declaración de Clases.
Ej.
•
•
•
Ciudadano
TipoCiudadano
DeclaracionJurada
NOTA: Los ComplexType y los SimpleType deberán tener el
prefijo Tipo.
Nombre de Elemento XML
para
definición
de
Atributos
(elementos
internos)
Utilizar nombres representativos empleando las mismas
convenciones de código Java para la declaración de Atributos.
Ej.
•
cedula
1 http://www.xfront.com/GlobalVersusLocal.html#ThirdDesign
Pág. 2
Lineamientos, estándares y convenciones para la creación de Documentos XSD y WSDL
Estándares y recomendaciones para el manejo de errores de Servicios Web
•
•
Nombre de archivo XSD
nombre
primerNombre
Utilizar como nombre de archivo el nombre del elemento XML
global definido en el documento XSD.
En el caso de encontrase más de un elemento global definido,
utilizar el nombre del elemento más representativo.
En el caso de que deban existir archivos con el mismo nombre
se crearían subcarpetas para almacenar los distintos
subdominios existentes.
<NombreDeElementoXML>.xsd
Ej.
•
•
•
Name Space
Ciudadano.xsd
TipoCiudadano.xsd
DeclaracionJurada.xsd
Todo elemento XML debe ser asociado a un XML Name Space
cuyo identificador debe cumplir el siguiente formato:
<url_organimo>/schema/<nombre_del_subdominio>
/<nombre_del_elemento_xml>
Ej.
•
•
http://www.cnti.gob.ve/schema/ciudadano
/Ciudadano
http://www.cnti.gob.ve/schema/ciudadano
/TipoCedula
Lineamientos generales para la creación de documentos WSDL:
1. Diseñar todo Servicio Web basando en el estilo Document/literal.
2. Emplear un Binding tipo SOAP/HTTP para todo Servicio definido.
3. Definir elementos wsdl:documentation para describir de forma general el servicio,
las operaciones, las entradas y salidas de cada operación.
Convenciones y Estándares para la creación de documentos WSDL:
Nombre de Servicio Web
Utilizar nombres representativos empleando las mismas
convenciones de código Java para la declaración de Clases.
Servicio<NombreDeServicio>
NOTA: Todos los servicios deberán tener la palabra
Pág. 3
Lineamientos, estándares y convenciones para la creación de Documentos XSD y WSDL
Estándares y recomendaciones para el manejo de errores de Servicios Web
“Servicio” como prefijo.
Ej.
•
•
Nombre de operación
ServicioIdentificacion
ServicioDeclaracionJurada
Utilizar nombres representativos empleando las mismas
convenciones de código Java para la declaración de Métodos.
Ej.
•
•
Mensaje de entrada de una
operación
identificarCiudadano
realizarDeclaracionJurada
Utilizar el nombre de la operación con el sufijo “Entrada”.
<NombreDeOperacion>Entrada
Ej.
•
•
Mensaje de salida de una
operación
identificarCiudadanoEntrada
realizarDeclaracionEntrada
Utilizar el nombre de la operación con el sufijo Salida.
<NombreDeOperacion>Salida
Ej.
•
•
Nombre de archivo WSDL
indentificarCiudadanoSalida
realizarDeclaracionJuradaSalida
Utilizar como nombre de archivo el nombre del Servicio Web
definido en el documento.
Servicio<NombreDeServicio>.wsdl
Ej.
•
•
Nombre del WSDL
(Atributo name del
elemento definitions)
ServicioIndentificacion.wsdl
ServicioDeclaracionJurada.wsdl
Utilizar el nombre del Servicio Web con el sufijo WSDL.
Servicio<NombreDeServicio>WSDL
Ej.
•
•
ServicioIndentificacionWSDL
ServicioDeclaracionJuradaWSDL
Pág. 4
Lineamientos, estándares y convenciones para la creación de Documentos XSD y WSDL
Estándares y recomendaciones para el manejo de errores de Servicios Web
Name Space
Todo Servicio Web declarado en un documento WSDL debe ser
asociado a un XML Name Space cuyo identificador debe
cumplir el siguiente formato:
<url_organimo>/servicio/Servicio<NombreDeServicio>
Donde Servicio<NombreDeServicio> es el nombre del
Servicio Web definido en el documento WSDL, el cuál coincide
con el nombre del archivo WSDL.
Ej.
•
•
PortType Name
http://www.cnti.gob.ve/servicio/ServicioI
dentificacion
http://www.onidex.gob.ve/servicio/Servici
oIdentificacion
Utilizar el sufijo “Definicion” para definir el PortType dentro del
WSDL
Servicio<NombreDeServicio>Definicion
Ej.
•
Binding Name
ServicioIdentificacionDefinicion
Utilizar el sufijo Implementacion para definir el Binding dentro
del WSDL
Servicio<NombreDeServicio>Implementacion
Ej.
•
Port Name
ServicioIdentificacionImplementacion
Utilizar el sufijo “Ubicacion” para definir el Port dentro del WSDL
Servicio<NombreDeServicio>Ubicacion
Ej.
•
soapAction
ServicioIdentificacionUbicacion
Emplear el nombre de la operación para el soapAction
correspondiente.
Ej.
•
•
identificarCiudadano
realizarDeclaracionJurada
Pág. 5
Lineamientos, estándares y convenciones para la creación de Documentos XSD y WSDL
Estándares y recomendaciones para el manejo de errores de Servicios Web
Estándares para el Manejo de Errores en un WSDL:
2. Para cada operación de un Servicio Web crear los siguientes Faults (tipos de errores):
•
Error de Sistema (System Fault): indica un error del sistema por alguna falla de
algún componente, Ej. caída de la red, servidor base de datos no disponible. El
nombre del Fault debe seguir la siguiente convensión:
<NombreDeOperacion>ErrorSistema
Ej. IdentificarCiudadanoErrorSistema
•
Error de Aplicación (Application Fault): indica un uso incorrecto del servicio por
ejemplo que un ciudadano no exista. El nombre del Fault debe seguir la
siguiente convensión:
<NombreDeOperacion>ErrorAplicacion
Ej. IdentificarCiudadanoErrorAplicacion
3. Se recomienda utilizar el siguiente tipo de dato complejo para la definición de cada
error especificado en el paso anterior:
<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
targetNamespace="<url_organimo>/schema/error/TipoError"
elementFormDefault="qualified">
<xsd:complexType name="TipoError">
<xsd:annotation>
<xsd:documentation>Tipo de Dato que define un error genérico</xsd:documentation>
</xsd:annotation>
<xsd:sequence>
<xsd:element name="codigo" type="xsd:string" minOccurs="1" maxOccurs="1"/>
<xsd:element name="descripcion" type="xsd:string" minOccurs="1" maxOccurs="1"/>
<xsd:element name="detallesTecnicos" type="xsd:string" minOccurs="0" maxOccurs="1"/>
</xsd:sequence>
</xsd:complexType>
</xsd:schema>
<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema xmlns:xsd="http://www.w3.org/2001/XMLSchema"
targetNamespace="<url_organimo>/schema/error"
elementFormDefault="qualified"
xmlns:error="<url_organimo>/schema/error/TipoError">
<xsd:import namespace="<url_organimo>/schema/error/TipoError" schemaLocation="TipoError.xsd"/>
<xsd:element name="ErrorSistema" type="error:TipoError">
<xsd:annotation>
<xsd:documentation>Tipo de Dato que define un error de sistema</xsd:documentation>
</xsd:annotation>
</xsd:element>
<xsd:element name="ErrorAplicacion" type="error:TipoError">
<xsd:annotation>
<xsd:documentation>Tipo de Dato que define un error de aplicación</xsd:documentation>
</xsd:annotation>
</xsd:element>
</xsd:schema>
Estándares para la definición de los códigos de Error en los Servicios:
1. Los códigos de error son reutilizables para diferentes servicios.
2. Los errores de sistema deben utilizar el prefijo “SIS” y los errores de aplicación el
prefijo “APP”
3. Los próximos 4 digitos es un número entero que identifica de forma única al error.
Pág. 6
Lineamientos, estándares y convenciones para la creación de Documentos XSD y WSDL
Estándares y recomendaciones para el manejo de errores de Servicios Web
4. El último carácter identifica la severidad de la condición de la excepción:
•
“F” (Fatal): Representa un error grave e indica que la opreación no debe
reintentarse.
•
“E” (Error): Representa un error no faltal e indica que la operación puede
reintentarse.
•
“W” (Warning): Indica que la operación se ha ejecutado pero existen
advertencias.
En consecuencia a partir de los errores que pudieran existir en lo servicios Web se debe crear
una tabla como la siguiente:
Codigo
SIS0001F
SIS0002E
APP5001E
Descripción
Error grave
Error de time-out a la base de
datos...
Error de acceso a la base de
datos
El ciudadano es menor de edad
APP5002W
APP5003E
Dirección no válida
El argumento X es invalido
SIS0003E
Detalles Técnicos
java.lang.OutOfMemoryError.....
java.net.ConnectException....
java.sql.SQLException.......
El ciudadano debe ser mayor de 18
años para solicitar su habilitación
como radioaficionado
No existe el código postal
java.io.UnsupportedEncodingExceptio
n
Recomendaciones para el Manejo de Errores en Servicios Web:
•
Todos los servicios deben reportar al consumidor, los errores técnicos que puedan
presentarse durante la ejecución.
•
Se presentarán casos en los que servicios que manejan excepciones requieren ser
consumidos por plataformas que no manejan excepciones. La recomendación en este
caso consiste en agregar un método adicional a la interfaz del servicio que permita a la
plataforma cliente nueva (la que no consume excepciones) consumir el servicio
mediante el uso de códigos de error. No se debe sacar un servicio de integración
aparte, sólo un método aparte dentro de la misma interfaz, si esto no funciona,
entonces si se debe construir un servicio nuevo de exposición que consuma el mismo
canónico.
•
Un servicio debe incorporar una funcionalidad de notificación cuando se ha producido
errores de conexión son sistemas proveedores, como base de datos, servicios,
sistemas de mensajería asíncrona, lectura de documentos xml, memoria, etc.
•
Un servicio debe incorporar una lógica para mantener un numero de reintentos hasta
alcanzar un umbral.
Pág. 7