Editor do Esquema de Ponto de Extensão

É possível abrir o editor do esquema de ponto de extensão de duas formas: como criando um novo ponto de extensão por produto ou abrindo um esquema de ponto de extensão existente.  Por convenção, os novos esquemas possuem o mesmo nome que o id do ponto de extensão com uma extensão de arquivo .xsd. Eles são colocados no diretório esquema na árvore do diretório 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 tem base nos mesmo conceitos que o editor de manifest de plug-in.  Possui duas páginas de formulário e uma página de origem.  Pelo fato de o esquema XML ser prolixo e poder ser complicado de ler em seu formulário de origem, você deve utilizar as páginas de formulário para a maioria das edições.  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 nosso projeto e clicando duas vezes no arquivo parsers.xsd.  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.

Todos os esquemas de ponto de extensão iniciam com uma declaração do elemento "extensão".  Incluiremos um novo elemento XML chamado "analisador."

  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 nos 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."  Defina a propriedade basedOn para com.example.xyz.IParser.  (Essa interface não existe ainda, mas a faremos depois.)

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

Incluiremos agora um atributo adicional que obtém os valores de uma lista de opções discreta.  Isso significa que precisamos criar uma restrição de enumeração do tipo de 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 fazer com que a caixa de diálogo de restrição apareça. 

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

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

Quando a caixa de diálogo estiver fechada, altere o atributo "use" para "default" e "value" para "always"  Isso estabelece o valor padrão.  Observe que a linha de status mostra uma mensagem de erro como se estivesse digitando o valor, desde que restrinja 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 New->Reference->parser no menu popup. Isso incluirá a referência do analisador para o compositor de seqüência.

  3. O padrão cardinal de referência é [1,1] que significa que pode haver exatamente um elemento "parser". Isso não é o que desejamos. Selecionamos a referência "parser" e alteramos a propriedade minOccurs na folha de propriedade para 0 e 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.

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 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 os marcadores 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" o editor de texto na caixa de combinação 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">
          <parser
             id="com.example.xyz.parser1"
             name="Sample Parser 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 Contorno 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.

Assim que terminar a documentação, é possível observar a documentação de referência, parsers.html, na pasta "doc".. Ela é construída por um construtor PDE registrado para reagir com as alterações nos arquivos de esquema de ponto de extensão. O documento resultante para esse exemplo parece com this.