Guia de Modelo Canônico - cissmart.com.br · 2.3.3 UTILIZAR HERANÇA 12 2.3.4 TRATAR REFERÊNCIA CIRCULAR 13 ... O propósito deste documento é definir e direcionar a criação

Guia de Modelo Canônico

Sobre a Sensedia

A Sensedia fornece soluções para reutilização de software e governança SOA (Arquitetura Orientada a Serviços). Empresas como Embraer, Itaú, Datasul, Bradesco Seguros e Nextel escolheram a Sensedia devido ao caráter inovador dos seus produtos e a utilização de melhores práticas em SOA. Com uma oferta liderada pelo Sensedia Repository, a empresa vem ajudando seus clientes a alcançarem benefícios como redução de custos de desenvolvimento, aumento da agilidade e do alinhamento entre as áreas de TI e negócio, além da redução do desenvolvimento duplicado. Visite www.sensedia.com/br.

© 2012, Sensedia S/A.

http://www.sensedia.com/br

Sensedia SOA Toolkit


2 Confidencial Restrito - www.sensedia.com/br

Conteúdo 1. INTRODUÇÃO 3

1.1 OBJETIVO 3 1.2 CAMPO DE APLICAÇÃO 3

1.3 PÚBLICO 3 1.4 PRÉ-REQUISITOS 3 1.5 GLOSSÁRIO 3 1.6 VISÃO GERAL 4 1.7 BENEFÍCIOS 4

2. DIRETRIZES DE ANÁLISE, DESIGN E MODELAGEM 7

2.1 IDENTIFICAR ENTIDADES E ATRIBUTOS 7

2.2 EXEMPLO DE MODELAGEM DE ENTIDADES 8 2.3 DIRETRIZES PARA O REFINAMENTO DO MODELO 9 2.3.1 UTILIZAR DESNORMALIZAÇÃO QUANDO APLICÁVEL 9 2.3.2 MAPEAR VALUE OBJECTS 11 2.3.3 UTILIZAR HERANÇA 12

2.3.4 TRATAR REFERÊNCIA CIRCULAR 13 2.3.5 OUTRAS CONSIDERAÇÕES 14

3. DIRETRIZES PARA IMPLEMENTAÇÃO 16

3.1 CRIAÇÃO DE ARQUIVOS XSDS 16 3.1.1 CRIAR UM XSD POR ENTIDADE DO MODELO CANÔNICO 16

3.1.2 CRIAR XSD’S COMUNS 16

3.1.3 MANTER ENTIDADES ESPECIALIZADAS NO MESMO XSD 17 3.1.4 NÃO CRIAR TIPOS COMPLEXOS COM ELEMENTOS ÚNICOS 18 3.1.5 NÃO TIPAR ELEMENTOS BASEADOS EM RESTRIÇÕES 18

3.2 PADRÕES GERAIS 18

4. DEFINIÇÃO DE NAMESPACE 22

4.1 DEFINIÇÃO ORIENTADA A ÁREA DE NEGÓCIO 22

4.2 DEFINIÇÃO ORIENTADA A ENTIDADES DOMINANTES 22

5. REFERÊNCIAS 23




1. Introdução

1.1 Objetivo

O propósito deste documento é definir e direcionar a criação de modelos canônicos, bem como suas boas práticas. Prover guias, padrões de design e políticas a serem seguidos e utilizados na construção das entidades ou objetos de negócios (XSDs) que fazem parte dos contratos dos serviços. Os XSDs fazem parte do contrato de serviço e são compartilhados com os consumidores dos serviços também, eles possuem grande potencial de reuso, pois podem ser utilizados em diversos contratos distintos de serviço, com isso é necessário criá-los com atenção. Os principais benefícios a serem obtidos com as diretrizes a serem apresentadas são:

Melhoria do desempenho através da diminuição da complexidade das

mensagens XML;

Padronização do Modelo Canônico com o objetivo de tornar o modelo mais

simples para ser entendido, evoluído e reutilizado;

Nortear as evoluções do modelo seguindo as melhores práticas;

1.2 Campo de Aplicação

Na definição de entidades canônicas para o desenvolvimento do contrato de interfaces de serviços. 1.3 Público

Arquitetos, desenvolvedores, analistas de dados e responsáveis pela governança dos serviços das áreas técnicas. 1.4 Pré-Requisitos

As seguintes versões dos padrões técnicos são utilizadas para modelo canônico:

XML-Schema 1.0 – http://www.w3.org/TR/xmlschema-1/;

OOAD – Análise e Projeto Orientados a Objetos;

Modelagem de Dados Relacional;

1.5 Glossário

XSD: são as representações técnicas dos objetos do negócio ou entidades,

são abstrações e independente de tecnologia;

Anti-Pattern: um padrão existente que não se aplica a determinadas

abordagens;




DDD: Domain Driven Design – uma abordagem para análise e modelagem de

entidades de negócio;

o Entidade: objeto que possui identidade de negócio. Ex. Cliente,

Fornecedor, Produto, etc;

o Value Object: objeto que possui atributos mas não possui identidade

do ponto de vista do negócio e são imutáveis. Ex: Sexo, Status, Tipo,

etc;

o Ubiquitous Language: Linguagem única acordada entre analistas de

negócio e desenvolvedores a fim de melhorar a comunicação entre as

áreas;

1.6 Visão Geral

O design de um modelo canônico deve ser independente de qualquer aplicação, deve representar o negócio da Empresa. Ou seja, o foco deste modelo é o negócio. Devido à flexibilidade do padrão XSD, o desenho do modelo canônico pode ser hierárquico ou relacional. Para a Empresa, o modelo a ser adotado será o hierárquico [2]. Assim sendo, o desenho poderá adotar as vantagens deste modelo, com isso se ganha em legibilidade, facilidade de processamento, interoperabilidade e baixo acoplamento. O modelo canônico de dados é a representação visual das entidades conceituais ou de objetos do mundo real em um domínio de negócio. Deve representar a compreensão da informação que a integração irá transportar entre os sistemas. A diretriz geral é para que o desenvolvimento do modelo canônico seja incremental durante os projetos SOA. Uma estratégia de definição global não é recomendada devido aos riscos inerentes por ser uma abordagem desacoplada a um contexto de identificação e design de serviço. Portanto, o processo de definição e análise de entidades canônicas pertencentes ao modelo inicia-se a partir de uma demanda. 1.7 Benefícios

A responsabilidade do modelo canônico é ser o padrão de comunicação dos serviços com o barramento. Isso significa que os serviços conectados ao barramento, tanto consumidores quanto provedores possam se comunicar através de um formato único. Desta forma, o modelo de dados da interface de um serviço (Service Schema Model) deve ser construído baseado no modelo canônico (Canonical Schema Model). Em termos técnicos, isso significa que o Schema do Serviço pode reutilizar tipos do modelo canônico, uma vez que esse Schema pode ser definido no WebService (WSDL) ou em outro arquivo XSD e desta forma utilizar o recurso de import para essa reutilização. Essa abordagem é baseada no pattern Canonical Schema [1].




Abaixo, segue a ilustração de como os Schemas dos Serviços são baseados nos Schemas do modelo canônico:

Os benefícios da abstração do modelo de canônico são:

Separação de papéis – os schemas dos serviços podem ser baseados no

schema do Modelo Canônico, ou seja, podem possuir ou herdar elementos

do modelo canônico. A responsabilidade do schema do serviço é construir os

parâmetros de entrada e saída deste serviço enquanto a responsabilidade do

schema do modelo canônico é definir as entidades pertinentes ao negocio da

companhia;

Reuso – a cada nova interface de serviço criada, o schema desta interface

pode ser baseada no schema do canônico. Isso significa que é possível

reutilizar estruturas (ou tipos) criadas no modelo canônico;

Isolamento – o modelo canônico pode estar sujeito a mudanças e evoluções.

A separação entre o schema da interface e o schema do canônico limita o

impacto na própria interface quando ocorrem mudanças. O schema de

serviço é definido no WSDL e o schema do canônico é um XSD isolado;




Modelo extensível – as entidades (schemas) podem ser extendidas;

Performance – serviços que são baseados no schema do canônico quando

orquestrados não necessitam de transformação entre eles, resultando no

ganho de performance;




2. Diretrizes de Análise, Design e Modelagem

2.1 Identificar Entidades e Atributos

Esta atividade tem o objetivo de localizar entidades e atributos relacionados com os serviços identificados no processo de desenvolvimento, mas que tenha o significado do negócio que operam. Neste caso, os documentos de especificação dos serviços devem ser analisados. Muitas vezes o documento de especificação dos serviços traz uma visão técnica, nesta etapa é importante que haja uma conversão para a visão de negócio, se necessário. Entidades normalmente são identificadas a partir de conceitos complexos do negócio, que possuem um comportamento bem definido e não podem ser descritas por tipos alfanuméricos. E atributos normalmente são identificados a partir de conceitos simples, que não possuem comportamento definido e com um único tipo de dado associado. Identifique atributos no modelo canônico, quando estes satisfazem a necessidade de memorizar informações referentes aos dados das mensagens dos serviços de integração. O processo de identificação das entidades e atributos é norteado por: 1. Analisar as especificações dos serviços: A análise deve focar nos valores de retorno das operações dos serviços. Esses valores de retorno são entidades canônicas potenciais. 2. Identificar entidade e atributos: entidades normalmente são identificadas a partir de conceitos complexos, que possuem um comportamento bem definido e que não podem ser descritas por tipos alfanuméricos. Por outro lado, atributos normalmente são identificados a partir de conceitos simples, que não tem comportamento definido e com um único tipo de dado associado.

Durante o processo de identificação de entidades e atributos deve-se ter o cuidado com os itens que possuem o mesmo significado. Se isso ocorrer, possivelmente eles representam o mesmo item de negócio. Verifique com cautela todas as operações do serviço, se a identificação e especificação do serviço foram bem realizadas, as operações possuem uma alta coesão e, portanto, as operações possuem grande chance de tratarem de informações co-relacionadas.

3. Identificar entidades base: entidades base são elementos como moeda, endereço, idade, sexo, contato. São entidades que podem ser reutilizadas em diversos contextos. Analise um conjunto de atributos de uma entidade que podem tornar-se uma entidade base. Normalmente são atributos com afinidade de negócio e que podem ser aplicados em diversos outros contextos. Por exemplo, a entidade endereço pode ser utilizada para a entidade Cliente como para a entidade Fornecedor.

Identificar Relacionamentos Uma associação é um relacionamento entre entidades que indica uma conexão com significado e interesse. Para encontrar as associações entre entidades, deve-se observar cada entidade e verificar se a informação representada está completa. Se não estiver, deve-se criar




uma associação entre uma entidade e outra a fim de complementar a informação necessária para que a entidade faça sentido. O relacionamento no modelo canônico quando for um relacionamento muito forte, significa que, analogamente a orientação a objeto, só deve existir quando a associação for do tipo composição e ainda com cardinalidade maior que um. Exemplo: 1 Pedido possui N ItemPedido. Os relacionamentos entre entidades muito independentes, exemplo Conta e Pessoa, deve ser evitada. Quando isso ocorrer pode-se desnormalizar para compartilhar elementos que coexistam entre as entidades ou mesmo utilizar a composição no modelo de interface de serviço. Mais detalhes, no item 2.3 (Refinamento do Modelo). 2.2 Exemplo de Modelagem de Entidades

O primeiro passo para a modelagem das entidades é entender o escopo que se desejar modelar. Para isso é necessário ter em mão as especificações que auxiliam neste processo. A figura abaixo ilustra a especificação de um serviço de “Pedido de Venda”:

O primeiro passo necessário para a identificação das entidades é entender o escopo do serviço com análise das operações. Toda operação tem entrada e saída de parâmetros, esses parâmetros podem ser entidades em potencial. Este exemplo trata-se de Pedido de Venda, portanto já se pode assumir que a entidade principal será “Pedido de Venda”. É possível perceber que existe “conjunto” de itens do pedido venda como parâmetro de entrada das operações, isso significa que esses conjuntos terão potencial para ser entidade. Desta forma, conseguimos identificar as seguintes entidades:




As entidades Pedido (SaleOrder) e Item de Pedido (SaleOrderItem)

O segundo passo será identificar os atributos, ou elementos, que compõem essas entidades. Para isso é necessário observar os parâmetros de entrada e saída dos serviços e encaixá-los nas entidades. Assim, a próxima figura ilustra as entidades e seus atributos:

Atributos identificados nas entidades

O próximo passo é identificar o relacionamento entre as entidades. Para isso pode-se observar a cardinalidade descrita nos parâmetros de entrada ou saída. No exemplo, é descrito que existe um conjunto ou lista de itens. Desta forma, a figura a seguir detalha o relacionamento entre Pedido e Item de Pedido e a cardinalidade empregada:

Relacionamento e cardinalidade entre as entidades

Assim sendo, as entidades do modelo canônico foram mapeadas e modeladas para atender o escopo do serviço. Para finalizar a modelagem ainda é necessário refinar o modelo conforme será descrito nas próximas seções. 2.3 Diretrizes para o Refinamento do Modelo

Com o modelo básico elaborado, ou seja, entidades identificadas, seus atributos e associações, o próximo passo é um refinamento seguindo as considerações abaixo: 2.3.1 Utilizar Desnormalização quando aplicável

Considere utilizar desnormalização: considerado um anti-pattern na modelagem relacional, esta estratégia é aderente ao pattern Contract Denormalization [1]. Este pattern prega a redundância para que os contratos dos serviços sejam mais simples e flexíveis.




Abaixo, segue um exemplo de desnormalização:

nome telefoneCelular telefoneResidencial

José 11 8232-0109 11 3232-0109

Maria 11 9893-9090 11 2343-0980

João 11 7456-0987 11 3456-0987

Campos telefoneCelular e telefoneResidencial estão desnormalizados.

Os campos de telefone fazem sentido no contexto de negócio, assim sendo, devem ser desnormalizados. Na abordagem relacional, essa entidade seria normalizada, ou seja, a entidade Telefone seria criada. Como e Quando utilizar Desnormalização: A desnormalização deve ser utilizada quando uma informação de uma entidade estiver associada fortemente a outra entidade negócio. Na UML é uma associação do tipo composição. Exemplo: A entidade fatura possui informações de endereço e cliente. Essa associação é muito forte, ou seja, não existe fatura sem cliente e sem endereço. Outro fator que determina a desnormalização é que esses atributos também devem ser desnormalizados, ou seja, para fatura faz sentido somente o nome inteiro do cliente e também o endereço por extenso, pois as informações nesses formatos facilitam a impressão das faturas. Abaixo, a comparação da mensagem desnormalizada (esquerda) em relação à mensagem normalizada (direita):

Abaixo, a comparação entre o design desnormalizado (esquerda) e o design normalizado (direita):




Conforme ilustrações acima, o design desnormalizado deve ser utilizado para o ganho de desempenho. É permitida a duplicação de elementos neste caso, as outras entidades de negócio ainda coexistem com a entidade fatura. Entretanto, para entidade fatura faz sentido que os elementos nome e endereço sejam desnormalizados. Principais benefícios desta abordagem:

Melhoria do desempenho provocada pela estrutura simplificada – o custo de

transformação é relativamente menor por ter menos tags e também a

diminuição do tamanho em bytes da mensagem;

Diminuição do número de entidades facilita entendimento e evolução do

modelo – em alguns casos como o primeiro exemplo não é necessário criar a

entidade Telefone;

Cuidados ao utilizar esta abordagem:

A desnormalização deve ser incentivada, entretanto ainda é necessário que

se pense em estruturas reutilizáveis. É comum entidades normalizadas

coexistirem com entidades que replicam elementos que foram

desnormalizados;

2.3.2 Mapear Value Objects

Para padronizar a nomenclatura dos tipos de objetos, iremos utilizar alguns conceitos (building blocks) da abordagem DDD, uma delas é o value object. Diferentemente do VO referenciado em programação OO, consideraremos Value Object um objeto que possui atributos mas não possui identidade do ponto de vista do negócio, além de ser imutável. Normalmente são implementados como restrições de domínio no banco de dados, ou através de uma tabela com apenas código e descrição. Ex: Sexo, Status, Tipo, etc. No modelo canônico os value objects são representados pelo estereótipo enumeration e devem ser mapeados com a finalidade de reuso. Eles têm a




particularidade de não serem instanciáveis, desta forma não se comportam como entidades e, assim sendo devem ser separados do modelo principal de negócio. O Value Object Sexo por exemplo, possui somente os valores “Feminino” e “Masculino”:

Principais benefícios desta abordagem:

Reutilização de entidades previamente mapeadas;

Diminuição da complexidade do modelo, essas entidades não são

confundidas com entidades de negócio.

Redução do número de artefatos XSDs, pois não há necessidade de criar um

XSD para cada Value Object;

Cuidados ao utilizar esta abordagem:

Utilize esta abordagem quando houver um domínio que não mude ou mude

muito pouco durante o ciclo de vida de execução;

2.3.3 Utilizar Herança

Existem situações que o uso de herança é recomendado, pois diminuem o tamanho da mensagem XML no barramento. Diferente da abordagem relacional, a tecnologia do modelo canônico permite a utilização deste recurso. Atualmente é comum o uso de composição no modelo canônico, uma vez que esse modelo foi baseado nos conceitos de entidade-relacionamento. Entretanto, o uso de herança é fortemente incentivado. Como e quando utilizar esta abordagem: O uso de herança é recomendado quando há um relacionamento de 1 para 1, onde há a necessidade de estender e reutilizar os elementos de uma determinada entidade. A figura abaixo mostra como uma entidade pode ser modelada com composição (esquerda) e herança (direita):




Ao usar esta abordagem, o tamanho XML produzido para a mensagem é menor. Abaixo, segue a comparação entre a mensagem gerada quando utilizada composição (esquerda) e utilizando herança (direita):

Principais benefícios desta abordagem:

Mensagem menos complexa incrementa o desempenho;

Redução do tamanho da mensagem;

2.3.4 Tratar Referência Circular

A referência circular também é denominada de relacionamento cíclico ou bidirecional. Essa característica herdada da modelagem entidade-relacionamento, provoca problemas como complexidade elevada do modelo e diminui significativamente o tempo de implantação. Como e quando utilizar esta abordagem: A referência circular existe quando há necessidade de ambos os lados de um relacionamento possuir informações do outro lado para compor uma mensagem.

Relacionamento cíclico entre Pessoa e Conta




Para minimizar o impacto do relacionamento, pode-se utilizar a abordagem de excluir o relacionamento e utilizar composição no modelo de interface do serviço que utiliza as duas entidades. A figura abaixo demonstra como deve ser o desenho:

Composição da Mensagem no Modelo de Interface do Serviço

No caso acima, a operação BuscarPessoa necessita retornar uma pessoa e suas contas. Entretanto não há a necessidade de criar relacionamento entre Pessoa e Conta, neste caso, basta compor a resposta da operação para ter a informação que se necessita. Principais benefícios destas abordagens:

Mensagem menos complexa incrementa o desempenho;

Redução do tempo de implantação. As referências cíclicas oneram

demasiadamente o tempo para resolver as referências;

2.3.5 Outras considerações

Tanto os produtores quanto os consumidores de uma integração devem

entender este formato. Quando a aplicação ou recurso da integração não

estiver adaptado ao formato canônico, uma transformação deve ser

realizada para adequar o formato da mensagem proprietária do nó da

integração para o formato canônico;

A estratégia é evoluir o modelo canônico conforme o surgimento das

demandas, isso não significa restringir-se apenas ao contexto da demanda.

Pense adiante, em um contexto um pouco mais abrangente. O foco no

negócio ajuda nesta granularidade e evita mudanças complexas no modelo

ao longo do tempo;

O modelo canônico é destinado a ser utilizado para comunicação entre

sistemas e, portanto, deve abranger apenas as entidades que são usadas na

camada de integração. As entidades que não são trocadas entre os sistemas

não devem ser representadas no modelo;

Verifique se existem modelos disponíveis que você pode usar como base.

Às vezes existem modelos específicos disponíveis de uma área, e às vezes




estes modelos também incluem conceitos genéricos como clientes, produtos,

contratos, preços, etc, que podem perfeitamente ser utilizados como fonte de

informação. Esses modelos podem ser obtidos com analistas de negócio,

analistas de processos, analistas de banco de dados, etc;

Durante a definição do modelo, solicite pessoas especialistas do domínio de

negócio para ajudar nesta tarefa, eles compreendem o negócio e podem

ajudar a garantir que o modelo reflita a empresa;

Ao nomear as entidades e elementos, procure utilizar termos que melhor

representem aquela informação dentro da empresa. Uma vez definido um

termo, evite utilizar termos sinônimos a ele no modelo (Ubiquitous Language)




3. Diretrizes para Implementação

3.1 Criação de Arquivos XSDs

3.1.1 Criar um XSD por Entidade do Modelo Canônico

Como no tópico anterior, iremos utilizar o termo Entidade da abordagem DDD. Nesta abordagem, entidade é um objeto que possui identidade de negócio. Elas devem possuir o seu próprio arquivo XML Schema. Exemplo: Contrato, Cliente, Transação, etc.

Um exemplo tipo definido para Cliente (Cliente.xsd): <?xml version="1.0" encoding="UTF-8"?>

<schema targetNamespace="http://Empresa.com.br/exemplo" elementFormDefault="qualified"

xmlns="http://www.w3.org/2001/XMLSchema" xmlns:cli="http://Empresa.com.br/exemplo">

<complexType name="ClienteType">

<sequence>

<element name="codigo" type="string"></element>

<element name="nome" type="string"></element>

<element name="telefone" type="string"></element>

</sequence>

</complexType>

<element name="cliente" type="cli:ClienteType"></element>

</schema>

Entidades que dependem de outras para “viver”, tal como Item de Pedido que possui associação de composição com a entidade pai Pedido, devem ter o seu tipo definido dentro do arquivo do seu tipo “pai”. Outras entidades que podem seguir essa diretriz são Value Objects que não são reutilizáveis, tal como Status do Pedido. <?xml version="1.0" encoding="UTF-8"?>


xmlns="http://www.w3.org/2001/XMLSchema" xmlns:ped="http://Empresa.com.br/exemplo">

<complexType name="PedidoType">

<sequence>


<element name="dataEntrega" type="date"></element>

<element name="status" type="ped:StatusPedidoType"></element>

<element name="telefone" type="ped:ItemPedidoType"

minOccurs="1" maxOccurs="unbounded"

></element>

</sequence>

</complexType>

<complexType name="ItemPedidoType">

<sequence>

<element name="codigoProduto" type="string"></element>

<element name="valor" type="decimal"></element>

</sequence>

</complexType>

<simpleType name="StatusPedidoType">

<restriction base="string">

<enumeration value="AguardandoPagamento" />

<enumeration value="Entregue" />

</restriction>

</simpleType>

<element name="pedido" type="ped:PedidoType" />

</schema>

3.1.2 Criar XSD’s Comuns

Value Objects e Entidades ‘genéricas’ devem estar agrupadas num único arquivo XML Schema comum.




Um exemplo de tipo definido para entidades comuns (Comum.xsd). <?xml version="1.0" encoding="UTF-8"?>


xmlns="http://www.w3.org/2001/XMLSchema" xmlns:sex="http://Empresa.com.br/exemplo">

<simpleType name="SexoType">


<enumeration value="Feminino" />

<enumeration value="Masculino" />

</restriction>

</simpleType>

<complexType name="TelefoneType">

<sequence>

<element name="telefone">

<simpleType>


<pattern value="\d{2}-\d{4}-\d{4}"></pattern>

</restriction>

</simpleType>

</element>

</sequence>

</complexType>

</schema>

3.1.3 Manter Entidades Especializadas no Mesmo XSD

Entidades Abstratas, aquelas que não fazem sentido existir em sua forma primitiva, devem ser mantidas no mesmo XSD. Exemplo: A entidade abstrata Pessoa não faz sentido de negócio se não for PessoaFisica ou PessoaJuridica. Um exemplo de tipo definido para Pessoa (Pessoa.xsd): <?xml version="1.0" encoding="UTF-8"?>


xmlns="http://www.w3.org/2001/XMLSchema" xmlns:pes="http://Empresa.com.br/exemplo">

<complexType name="PessoaType" abstract="true">

<sequence>


</sequence>

</complexType>

<complexType name="PessoaFisicaType">

<complexContent>

<extension name="PessoaType">

<sequence>

<element name="cpf" type="string"></element>

</sequence>

</extension>

</complexContent>

</complexType>

<complexType name="PessoaJuridicaType">

<complexContent>

<extension name="PessoaType">

<sequence>

<element name="cnpj" type="string"></element>

</sequence>

</extension>

</complexContent>

</complexType>

<element name="pessoaFisica" type="pes:PessoaFisicaType"></element>

<element name="pessoaJuridica" type="pes:PessoaJuridicaType"></element>

</schema>

CUIDADO: Siga essa recomendação somente quando houver a entidade abstrata, no caso de especialização derivada de uma entidade de negócio manter as entidades em arquivos XSD’s separados. Exemplo: Assinatura e Linha que são entidades de negócio possuem seus próprios XSD’s.




3.1.4 Não Criar Tipos Complexos com Elementos Únicos

Não é necessário criar tipos com elementos únicos. Estes tipos prejudicam a geração da mensagem XML, pois deixam as mensagens maiores. 3.1.5 Não Tipar Elementos Baseados em Restrições

Restringir os elementos não é uma boa prática na implementação do modelo canônico, pois interfere na interoperabilidade entre sistemas. Portanto, é necessário não impor restrições quanto a tamanho, valores válidos e etc. Dentro deste contexto utilizar restrições não faz sentido ao definir tipos aos elementos. Abaixo, o trecho compara entre a definição de tipos com restrições (esquerda) e sem restrições (direita):

3.2 Padrões Gerais

1. Na criação de um tipo, dê preferência de uso para os elementos em relação aos

atributos. O uso de atributos fere o Padrão Hierárquico, prejudica a legibilidade

do documento XML além dos atributos possuirem limitações:

1.1. atributos não podem conter múltiplos valores;

1.2. atributos não são facilmente expansíveis (para incorporar futuras

mudanças);

1.3. atributos não podem descrever estruturas;

2. Todos os elementos e atributos devem usar o padrão UCC lower camel case,

por exemplo, (telefoneCelular), evitar hífens, espaços, caracteres especiais ou

outra sintaxe;

3. Legibilidade é mais importante do que o comprimento da tag. Há sempre um

questionamento entre o tamanho do documento e a legibilidade, sempre que

possível, de preferência a legibilidade;

4. Evite abreviações e siglas para o elemento, atributo e nomes de tipo.

Exceções devem restringir-se a siglas, acrônimos e abreviações conhecidas. Por

exemplo: ID (identificador), NF (Nota Fiscal) ou quando o nome for extenso;

5. Todos os tipos novos criados devem possuir o sufixo “Type”. Por exemplo:

ExameType e MedicoType;




6. Enumerações não devem usar nomes de números, e os valores devem ser no

padrão UCC camel case;

7. Os nomes de atributos não devem incluir o nome da estrutura da qual ele está

contido. Por exemplo: nomeCliente deve ser apenas nome dentro do tipo Cliente;

8. Defina o atributo elementFormDefault = "qualified" no elemento do esquema do

seu esquema. Esse é o padrão utilizado pelo barramento, portanto traz o

benefício do desempenho ao utilizar esta abordagem;

9. Versionamento do Schema – para facilitar a identificação da versão pode-se

adicionar um comentário no arquivo contendo uma descrição funcional da

entidade, Versão e Histórico de Revisão: <?xml version="1.0" encoding="UTF-8"?>

<schema xmlns="http://www.w3.org/2001/XMLSchema"

elementFormDefault="qualified"

targetNamespace="http://Empresa.com.br/exemplo">

<annotation>

<documentation>

Schema para Produto

Versao: 1.0

Historico de revisao;

1.0 01-01-2011 Criacao do schema de produto

1.1 15-05-2011 Inclusão do elemento estoque

</documentation>

</annotation>

...

</schema>

10. Somente importe namespaces que são usados dentro do schema. Não importe

qualquer schema que não é referenciado no schema;

11. Não modelar os tipos complexos como se fosse modelar banco de dados

relacional:

11.1. Evitar o acoplamento de schemas em relação aos modelos físicos de

banco de dados. Isto inevitavelmente conduz para o acoplamento do

contrato para implementação, que pode inibir a evolução do contrato do WS;

12. Ao construir o XSD tenha em mente sempre o conteúdo do XML que ele irá

validar;

13. Na construção utilize indentação de 3 caracteres de espaços em branco para

organizar o XSD e torná-lo legível. Por padrão, o Eclipse já vem configurado com

essa convenção;

14. Enumerations:

14.1. Nomes do tipo enumeration devem estar no singular, não no plural;

14.2. Se um tipo é criado com um enumeration que necessita ser atualizado

regularmente, isto poderá significar que uma mudança grande no schema




será necessária para incrementar as opções do enumeration. Por isso, não

utilize enumerations para tipos voláteis (suscetíveis a mudanças);

14.3. Não comece o nome de um item de um enumeration com números, por

exemplo, “31Dias”;

14.4. Enumerations não devem conter mais que 15 itens;

14.5. Não use códigos;

15. MinOccur – o valor padrão é “1”. Seu valor pode ser qualquer número inteiro que

não seja negativo. Como padrão utilize o valor “0” para torná-lo opcional;

16. MaxOccur – o valor padrão é “1”. Utilize um número inteiro qualquer maior que

zero, e utilize “unbounded” para tornar infinito;

17. Adicione boas anotações para tipos e elementos quando necessário. Assegure

que as tags de anotações (annotation tag) estão sendo utilizadas e que os

comentários não possuem códigos HTML;

18. Um elemento que tem mais de um atributo deve ser declarado como um tipo

complexo, conforme prevê o pattern Venetian Blind. Exemplo: elemento data

com atributos dia, mês e ano;

19. Utilize xsd:import se os namespaces são diferentes. Um schema pode conter

múltiplos elementos xsd:import, que devem aparecer no início de um

xsd:schema;

20. Utilize xsd:include se os namespaces são os mesmos. Um schema pode conter

múltiplos elementos xsd:include, que devem aparecer no início de um

xsd:schema;

21. xsd:Import e xsd:include devem ser utilizado para quebrar o tamanho do arquivo

XSD e também para garantir o reuso;

22. Os nomes dos arquivos XSD devem respeitar o padrão UCC camel case. Por

exemplo, NotaFiscal.xsd;

23. Não criar tipos no formato “Lista”. Esses tipos não representam entidades de

negócio prejudicando a legibilidade e manutenção dos arquivos XSD’s. Não criar

o tipo complexo com cardinalidade 0 ou 1 para N, essa cardinalidade deve ser

definida no contrato do serviço, ou seja, no schema do WSDL;

24. Não crie restrições para os atributos, tipos e elementos. Exemplo: elementos

opcionais, limite de tamanho de campos, etc. Criar restrições nas entidades

prejudica o reuso e a interoperabilidade;

25. Documente o máximo possível as entidades, sempre com foco no negócio;




26. Visualize o XML a ser gerado com o propósito de torná-lo mais simples,

diminuindo o número de tags para que a mensagem tenha menor tamanho ao

trafegar no barramento e seja mais performático para transformação;

27. Não crie elements para encapsular simpleTypes com restrições para tipos

primitivos (int, string, float, etc), tipos primitivos possibilitam maior legibilidade,

simplicidade na criação dos stubs por parte dos clientes e XML menores;




4. Definição de Namespace

Na implementação dos XSD’s, o Namespace é um recurso utilizado com a finalidade de prover os seguintes benefícios:

Organização dos arquivos;

Facilitar o entendimento do negócio e do modelo canônico;

Otimizar a evolução dos canônicos provocado pelos itens citados acima;

Para definir os namespaces onde as entidades do modelo canônico serão organizadas, pode-se utilizar as abordagens a seguir:

4.1 Definição Orientada a Área de Negócio

Um namespace pode ser definido a partir da área de negócio. Assim sendo, o nome do namespace deverá seguir o padrão http://Empresa.com.br/model/<processo>/. Por exemplo: http://Empresa.com.br/model/cardiologia

4.2 Definição Orientada a Entidades Dominantes

Um namespace pode ser definido a partir do domínio de uma entidade na qual a nova entidade está relacionada. Por exemplo: a entidade Assinatura é dominante, ou seja, possui grande valor de negócio e concentra grande quantidade de relacionamentos. Isso significa que a entidade Assinatura se relaciona com outras entidades fortes como Pessoa, Conta, Ordem de Venda, etc, além de ter diversos “filhos” associados Campanha, Promoções, Recarga. Assim sendo, o nome do namespace deverá seguir o padrão <entidade dominante>. Exemplo: assinatura.

Recomenda-se para a Empresa, utilizar a primeira abordagem devido a diversidade de áreas de negócio do grupo. Desta maneira as unidades de negócio podem ter visões diferentes de uma determinada Entidade.




5. Referências

[1] Erl, T. SOA Design Pattern. Prentice Hall, 2009. [2] HIERARCHICAL VS. RELATIONAL XML SCHEMA DESIGNS. Disponível em: <http://www.exchangenetwork.net/dev_schema/schemadesigntype.pdf >. Acesso em: 17 fev. 2011.

Documents

Guia de Modelo Canônico - cissmart.com.br · 2.3.3 UTILIZAR HERANÇA 12 2.3.4 TRATAR REFERÊNCIA CIRCULAR 13 ... O propósito deste documento é definir e direcionar a criação