Editor de Esquema do Ponto de Extensão

Você pode abrir o editor de esquema do ponto de extensão de duas maneiras: como um produto secundário da criação de um novo ponto de extensão ou abrindo um esquema existente de ponto de extensão.  Por convenção, os esquemas novos possuem o mesmo nome que o ID do ponto de extensão com uma extensão de arquivo .exsd. Eles são colocados no diretório schema na árvore de diretórios do plug-in.  

Quando um novo ponto de extensão é criado no PDE, o arquivo do esquema inicial também será criado e o editor do esquema será aberto para edição. É possível definir o esquema agora ou fechá-lo e fazer isso depois. Fazer um esquema de ponto de extensão completo permite que o PDE ofereça assistência automática aos usuários do ponto de extensão.

O editor de esquema PDE baseia-se nos mesmos conceitos que o editor de manifesto de plug-in.  Ele possui duas páginas de formulário e uma página de origem.  Como o esquema XML é detalhado e pode ser difícil de ser lido no formulário de origem, você deve utilizar as páginas de formulário para a maior parte da edição.  A página de origem é útil para ler o código fonte resultante.

Exemplo: criando esquema para o ponto de extensão "Analisador Amostra"

Criamos anteriormente o ponto de extensão "Analisador de Amostra" e o esquema inicial. Podemos agora abrir o esquema indo para a pasta esquema do projeto e dando um clique duplo no arquivo parsers.exsd.  Isso abrirá o editor de esquema.

Desejamos fazer o seguinte:

  1. Definir os elementos e atributos XML válidos para o ponto de extensão.
  2. Definir a gramática (gabarito de conteúdo).
  3. Fornecer fragmentos de documentação que serão incorporados em um documento de referência.

Cada esquema do ponto de extensão inicia com uma declaração do elemento "extension".  Nós adicionaremos um novo elemento XML denominado "parser."

  1. Pressione o botão Novo Elemento na seção Elementos dos Pontos de Extensão.
  2. Mova para exibição Propriedades e altere seu nome de "New_Element" para "parser"
  3. Enquanto o novo elemento ainda estiver selecionado, pressione o botão Novo Atributo. Isso criará "new_attribute" como seu filho. Altere seu name para "id" e use para "required" na folha de propriedade.
  4. Enquanto ainda estiver na folha propriedade, pressione o botão "Clonar esse Atributo" disponível na barra de ferramentas local. Isso criará uma cópia do atributo.  Isso é útil porque permite definir rapidamente todos os atributos sem sair da folha de propriedade.
  5. Altere o nome do novo atributo em "name."
  6. Clone o atributo novamente. Nesse momento, altere o nome para "class."  Esse atributo será utilizado para representar um nome completamente qualificado da classe Java que deve implementar uma interface Java específica. Precisamos especificar isso para que o PDE possa, depois, tirar vantagem disso. Altere kind de "string" para "java."  Define a propriedade basedOn para com.example.xyz.IParser.  (Esta interface ainda não existe, mas nós a criaremos posteriormente.)

Então, o editor do esquema deveria parecer com este:

Editor do esquema de ponto de extensão - Página de Definição

Agora adicionaremos um outro atributo que obtém valores de uma lista discreta de opções.  Isso significa que precisamos criar uma restrição de enumeração do tipo base string.  Além disso, definiremos um valor padrão para o atributo.

  1. Enquanto o elemento "parser" estiver selecionado, pressione  o botão Novo Atributo. Altere seu nome na folha de propriedade para "mode."
  2. Clique na célula de valor da propriedade "restriction" para tornar visível o diálogo de restrição. 
  3. Altere o tipo de restrição de "none" para "enumeration."
  4. Inclua as seguintes três opções: "never," "always" e "manual."  (Estes são nossos três modos hipotéticos para a extensão parser.)

A caixa de diálogo restrição deveria parecer com esta:

Diálogo de Restrição do Tipo

Quando o diálogo for fechado, altere o atributo "use" para "default" e o atributo "value" para "always."  Isso estabelece o valor padrão.  Observe que a linha de status mostra uma mensagem de erro enquanto você digita o valor, uma vez que restringe os valores válidos para as três opções de enumeração. Assim que terminar de digitar, a mensagem de erro deveria sair porque "always" é um valor válido.

Agora que definimos todos os elementos e atributos, precisamos definir a gramática. Nosso objetivo é definir que o elemento "extension" pode ter qualquer número de elementos "parser" como filhos. 

  1. Selecione o elemento "extension". Seu gabarito de conteúdo inicial mostra um compositor de seqüência vazia.
  2. Selecione o compositor de seqüência e selecione Novo->Referência->parser no menu pop-up. Isso incluirá a referência do analisador para o compositor de seqüência.
  3. A cardinalidade padrão de referências é [1,1], o que significa que pode haver exatamente um elemento "parser". Isso não é o que desejamos. Selecionamos a referência "parser" e alteramos maxOccurs para "unbounded."

Depois de definir a gramática, a aproximação DTD abaixo da seção gramática mostra que a gramática para o elemento selecionado apareceria no DTD.  Essas informações são fornecidas para ajudar os desenvolvedores que ainda estão mais confortáveis com os DTDs que com os esquemas XML.

Editor do esquema de ponto de extensão - gramática do elemento

Agora que definimos elementos válidos, atributos e gramática, precisamos fornecer algumas informações sobre o ponto de extensão. Há dois tipos de fragmentos de documentação de esquema:

O primeiro tipo de fragmento é fornecido na página Definição de manifest do esquema. Conforme seleciona elementos e atributos, é possível incluir texto pequeno sobre eles na seção "Descrição". O formato esperado é em HTML (como com Javadoc) e o texto será copiado como está no documento de referência final.

  1. Selecione o atributo "id"' do elemento "parser" e digite o seguinte no editor de Descrição:
    um nome único que será utilizado para fazer referência nesse analisador.
  2. Selecione o atributo "name" e inclua o seguinte texto:
    um nome que possa ser traduzido que será utilizado para apresentar esse analisador na UI.
  3. Selecione o atributo "class" e inclua o seguinte texto (observe as marcações HTML):
    um nome completamente qualificado da classe de Java que implementa a interface<samp>com.example.xyz.IParser</samp>.
  4. Selecione o atributo "mode" e inclua o seguinte:
    um flag opcional que indique a freqüência de execução dessa ocorrência de analisador (o padrão é <samp>always</samp>).

Agora temos que fornecer uma descrição de texto pequeno do próprio ponto de extensão. Para fazer isso, alternamos para a página de Documentação:

  1. Escolha "Visão Geral" na caixa de combinação acima do editor de texto e inclua o seguinte texto:
    Esse ponto de extensão é usado para analisadores adicionais de plug-in. Os analisadores realmente não funcionam - temos que usá-los somente como exemplos do esquema de ponto de extensão.
    Pressione Aplicar.
  2. Escolha "Exemplos" na caixa de combinação e inclua o seguinte texto:
       O exemplo a seguir é da utilização do ponto de extensão:   <p>
       <pre>
          <extension point="com.example.xyz.parsers">
          <analisador
             id="com.example.xyz.parser1"
             name="Analisador de Amostra 1"
             class="com.example.xyz.SampleParser1">
          </parser>
    </extension>    </pre>
       </p>
    

    Pressione Aplicar.

  3. Selecione "Informações API" e inclua o seguinte texto:
    Os plug-ins que desejem estender esse ponto de extensão devem implementar a interface <samp>com.example.xyz.IParser</samp>.
    Pressione Aplicar.
  4. Selecione "Implementação Fornecida" e inclua o seguinte texto:
    O Plugin XYZ fornece a implementação padrão do analisador.
    Pressione Aplicar.
Nota: deve ser dada consideração especial ao fornecer exemplos. Normalmente, o PDE trataria o texto fornecido como HTML não-processado e não respeitaria linhas novas e espaços em branco maiores que um caractere (isto é, espaço em branco ignorável). Isso é para ser esperado quando relacionado a texto regular, mas é extremamente indesejável ao fornecer exemplos, onde a tabulação e o alinhamento vertical são importantes se o exemplo tiver que ser bom. O PDE tem um compromisso com essa situação: se detectar a marcação HTML <pre>, tomará o conteúdo como está (preservando todos os caracteres sem modificação) até que a marcação de fechamento </pre> seja vista. Isso ocorre porque podemos fornecer um exemplo como acima e estarmos certos que ele parecerá bom no documento de referência final.

Você pode já ter observado que conforme você digita a documentação, mais e mais elementos na exibição Outline do editor recebe uma sobreposição de elemento de imagem "pen". Esse pequeno indicador informa que o elemento em questão possui algum texto associado a ele - uma forma rápida de verificar se está faltando documentação em algum lugar no documento.

Outline do editor do esquema de ponto de extensão

Depois de concluirmos com a documentação, poderemos ver a documentação de referência. Isso pode ser feito de duas maneiras. Todo o tempo durante o trabalho, você pode visualizar o documento de referência selecionando o item Visualizar Documento de Referência no menu pop-up. Alternativamente, você pode configurar as preferências do PDE (Preferências>Desenvolvimento de Plug-in>Compiladores, sob a guia Esquema) para criar automaticamente a documentação de referência em cada alteração do arquivo de esquema. Independente do método para criá-lo, o documento resultante para este exemplo seria semelhante a este.

 
Copyright IBM Corporation e outros 2000, 2003