Gerenciando campos personalizados usando o serviço de documentos REST nos serviços IBM Lotus Quickr 8.1.1 para WebSphere Portal

Este artigo apresenta o suporte de campo personalizado do serviço de documento Representational State Transfer (REST) nos serviços do IBM® Lotus® Quickr™ 8.1.1 para IBM WebSphere® Portal, também chamado Java™ 2 Platform, versão Enterprise Edition (J2EE) do Lotus Quickr. Nós explicaremos o conceito dos campos personalizados, discutiremos o modelo de programação para gerenciar campos personalizados com o serviço de documento REST do Lotus Quickr, e demonstraremos um cenário de negócios para a extensão do conjunto principal de atributos do documento.

Derek Carr, Advisory Software Engineer, IBM

Derek Carr é Engenheiro de Software Consultor na IBM e trabalha com a equipe Lotus Quickr no Research Triangle Park, NC. É possível entrar em contato com ele pelo e-mail dwcarr@us.ibm.com.



Xiao Pei Liu, Software Engineer, IBM

Xiao Pei Liu é Engenheira de Software e trabalha no teste de API para equipe do IBM Lotus Quickr em Pequim, na China. Entre em contato com ela pelo e-mail: liuxpei@cn.ibm.com.



Zhang Zi Xuan, Software Engineer, IBM

Zhang Zi Xuan é engenheiro de software e trabalha com a equipe do Lotus Quickr Service em Pequim, na China. Entre em contato com Zi Xuan pelo e-mail zhangzix@cn.ibm.com.



Bing Feng Han, Software Engineer, IBM

Bing Feng Han é Engenheiro de Software e trabalha com a equipe do Lotus Quickr Connector nas instalações da IBM em Pequim, na China. Entre em contato com Bing Feng pelo e-mail bfhan@cn.ibm.com.



23/Fev/2010

Nota do editor: Conhece muito sobre esse tópico? Deseja compartilhar seu conhecimento? Participe hoje do programa de wiki do software IBM Lotus.

Pré-requisitos

Este documento deve ser especialmente útil para usuários que estão pensando em migrar ou integrar conteúdos de repositórios de conteúdo existentes que suportem atributos customizados. Para obter o máximo deste artigo, deve-se possuir conhecimento sobre:

  • Serviços Lotus Quickr para WebSphere Portal
  • Serviços REST
  • Atom Syndication Format e Atom Publishing Protocol (AtomPub)
  • Programação Java
  • Apache Abdera, que é uma implementação Java de protocolos Atom e AtomPub

Visão geral do suporte a campos personalizados no Lotus Quickr 8.1.1

O Lotus Quickr é um software de colaboração em equipe que o ajuda a compartilhar conteúdos, colaborar e trabalhar online com suas equipes de maneira mais rápida. O componente de biblioteca de documentos do Lotus Quickr permite o gerenciamento de todos os seus arquivos de equipe em um ambiente de colaboração com capacidades aprimoradas, incluindo suporte a versão, gerenciamento de fluxo de trabalho e a capacidade de adição de campos personalizados ao documento.

Campos personalizados

Em geral, metadados são necessários para descrever o conteúdo primário do documento. Cada documento no Lotus Quickr possui um conjunto padrão de campos de metadados. O conjunto comum de metadados inclui nome do arquivo, autor, data de criação e data de atualização; no entanto, em alguns casos, os metadados comuns não são suficientes para descrever as propriedades do arquivo.

Como resultado, foram introduzidos campos personalizados, que são um conjunto de propriedades estendidas que os usuários podem definir e fornecer para um tipo específico de documento. Os campos customizados também são muito úteis na busca de conteúdos no Lotus Quickr, onde os campos customizados são definidos por uma folha de propriedade associada aos documentos por tipo de documento.

Folha de Propriedade

Uma folha de propriedade contém vários campos que são projetados por usuários para satisfazer necessidades comerciais específicas. Os tipos de campo, opções, valores padrões, ordens de campo, etc., são definidos pelo usuário para anexar elementos de formulários de dados customizados ao documento.

Folhas de propriedades são geralmente definidas e usadas localmente em uma biblioteca de documentos, mas um administrador do Lotus Quickr pode definir folhas de propriedades compartilhadas que podem ser usadas em qualquer uma das bibliotecas de documentos no servidor do Lotus Quickr.

Para criar uma folha de propriedade, vá até página principal de seu local na interface com o usuário da Web (UI), expanda Manage Document Elements, selecione Property Sheets e então clique em Create Property Sheet (veja a Figura 1).

Figura 1. Crie a Folha de Propriedades na UI da Web
Create Property Sheet on Web UI

Para adicionar campos à folha de propriedades, clique em Add Fields do lado direito da janela Create Property Sheet e insira o nome do campo, valores da opção, estilo de exibição, valores padrões, etc. (veja a Figura 2).

Figura 2. Adicione campos à folha de propriedade
Add fields to the property sheet

Tipo de documento

Folhas de propriedade fornecem conjuntos reutilizáveis de definições de campo. Folhas de propriedade múltiplas podem ser anexadas ao documento e o conjunto de folhas de propriedade disponíveis para qualquer documento é definido pelo tipo de documento associado do documento.

Um tipo de documento fornece um mecanismo pelo qual os comportamentos de um documento podem ser definidos, incluindo modelos de documentos, versões, definições de fluxo de trabalho e campos personalizados. Quando o documento de um tipo particular é transferido por upload, todos esses parâmetros pré-definidos entram em vigor.

Como descrito acima, os campos customizados não são definidos no tipo de documento diretamente; ao invés disso, eles são definidos em uma folha de propriedade e então adicionados ao tipo de documento. Similar às folhas de propriedade, os tipos de documento são geralmente definidos no escopo da biblioteca de documentos, mas podem ser definidos para todas as bibliotecas de documentos pelo administrador do Lotus Quickr.

Para gerenciar seus tipos de documento, vá à página principal do seu local na UI da Web, expanda Manage Document Elements e selecione Document Types. Ao criar ou atualizar um tipo de documento, pode-se selecionar folhas de propriedade para serem adicionadas ou removidas do tipo de documento.

Para adicionar uma folha de propriedade ao criar um tipo de documento, clique no link Add an existing property sheet na seção Property Sheets e na janela Choose Property Sheet, selecione a folha de propriedade que deseja adicionar (aqui, New Property Sheet; veja a Figura 3).

Figura 3. Adicione uma folha de propriedade a um tipo de documento criado
Add property sheet to newly created document type

Aplique campos personalizados a um documento

Depois de ter criado as folhas de propriedade e tipos de documentos em seu local, pode-se fazer o upload ou criar documentos e selecionar seu tipo de documento esperado. Deve-se, então, inserir as propriedades que foram definidas na folha de propriedade; os valores inseridos são transformados nos metadados do documento.

Para escolher um tipo de documento e inserir os campos definidos pela sua folha de propriedade, siga etapas a seguir:

  1. Selecione Upload na página principal do local e, na janela Upload Files, clique no link Change na seção Document type (veja a Figura 4).
  2. Selecione o tipo de documento que deseja usar na janela Choose Document Type (aqui, New Document Type).

Observe que as propriedades no tipo de documento são mostradas em uma nova seção Document type properties, na parte inferior da página.

Figura 4. Escolha o tipo de documento e os campos na folha de propriedade
Choose document type and fields in property sheet

Suporte a campo personalizado nos serviços públicos do Lotus Quickr

O Lotus Quickr também inclui um conjunto de serviços públicos (APIs) para acessar conteúdos gerenciados pelo Lotus Quickr. Ao usar esses serviços, pode-se construir aplicativos customizados ou integrar conteúdos do Lotus Quickr com outros aplicativos.

O serviço de documento REST é uma parte principal dos serviços públicos do Lotus Quickr, permitindo acessar e atualizar, de maneira programática, muitas das informações nas bibliotecas de documentos do Lotus Quickr usando um modelo de programação RESTful que segue o Atom Publishing Protocol (RFC 5023) e implementa o Atom Syndication Format (RFC 4287).

Começando pelo Lotus Quickr 8.0 o serviço de documentos REST fornece a capacidade de criar, recuperar, atualizar e excluir documento nas bibliotecas do Lotus Quickr, mas campos personalizados não eram suportados até o Lotus Quickr 8.1.1, lançado em dezembro de 2008.

Nas seções a seguir, este artigo introduz o modelo de programação de gerenciamento de campos personalizados no serviço de documento REST e demonstra como usar os serviços em aplicativos reais, usando um exemplo de programa.


Gerenciando campos personalizados usando o modelo de programação REST

NOTE: Na seção anterior deste artigo, usamos o tempo "folha de propriedade" para descrever tanto as definições de campo personalizado quanto os campos personalizados implementados em um documento. No entanto, no modelo de programação REST, o termo "tipo de folha de propriedade" é usado para descrever a definição de campos personalizados. Após a implementação de um tipo de folha de propriedade por um documento, os valores dos campos personalizados do tipo de folha de propriedade são chamados de "folha de propriedade". No restante deste artigo, usamos os novos termos no modelo de programação REST.

Criando um tipo de folha de propriedade

Para criar um tipo de folha de propriedade em uma biblioteca, pode-se enviar pedido POST ao URL de alimentação do tipo de folha de propriedade, http://<host>:<port>/dm/atom/library/<libraryId>/propertysheettypes/feed, fornecendo uma entrada Atom do tipo da folha de propriedade no corpo do pedido HTTP (veja a Listagem 1).

Listagem 1. Pedido para a criação de um tipo de folha de propriedade
POST /library/08ca5f0044ab2d6a858eed71ca20d4cf/propertysheettypes/feed HTTP/1.1
Host: example.com
Content-Type: application/atom+xml
Content-Length: nnnn
Authorization: Basic ...

<entry xml:lang="en" xmlns:td="urn:ibm.com/td">
    <id>urn:lsid:ibm.com:td:8b40f50049641d8789a2d97accc4bd33</id>
    <td:uuid>8b40f50049641d8789a2d97accc4bd33/<td:uuid>
    <category term="propertysheettype" scheme="tag:ibm.com,2006:td/type" 
    label="propertySheetType"></category>
    <author>
      <uri>uid%3Dquikradm%2Co%3Ddefault+organization</uri>
      <name>quikradm</name>
      <email></email>
    </author>
    <title type="text">example</title>
    <updated>2008-04-23T00:40:42.141Z</updated>
    <summary type="text">example Property Sheet Type</summary>
<content type="application/atom+xml" 
src="library/108c368048681104a123e3be2a21d9f5/propertysheettype">
  <meta:propertySheetTemplate xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
  xmlns:clb="http://content.ibm.com/clb/1.0" 
  xmlns:meta="http://metadata.model.xsd.clb.content.ibm.com/1.0">
  <meta:property xsi:type="meta:ClbPropertyType" dataType="string" 
  maxLength="2048" multiple="false" propertyId="clb:ps1" 
  propertyName="clb:p_a6aa8d78-bc9e-4a35-a243-000aaaa8af12" 
  readonly="false" required="false" searchable="true">
    <meta:label label="Name" lang="en" />
    <meta:style name="ibm:textVariant" value="medium" />
  </meta:property>    <meta:property xsi:type="meta:ClbPropertyType" 
  dataType="boolean" multiple="false" propertyId="clb:ps2" 
  propertyName="clb:p_f4179b4b-9c29-45ea-a18b-3e507002015d" 
  readonly="false" required="false" searchable="true">
    <meta:label label="Gender" lang="en" />
  </meta:property>
</meta:propertySheetTemplate>
</content>

    <td:contrainedMimeType>application/atom+xml<td:contrainedMimeType>
    <td:isExtracted>true<td:isExtracted>
</entry>

A entrada Atom acima contém um elemento <content> que armazena a definição do modelo XML da folha de propriedade que possibilita que campos personalizados sejam definidos.

O elemento <propertySheetTemplate> pode conter zero ou mais elementos <property> que definem uma parte individual de campos personalizados no sistema.

Cada elemento deve conter um atributo propertyld.attribute que defina um identificador de propriedade exclusivo em um <propertySheetTemplate> único.

Além disso, há vários outros atributos suportados. A Tabela 1 lista todos os atributos suportados para o elemento <property>.

Tabela 1. Atributos suportados no elemento <property>
AtributoDescrição
datatypeO atributo necessário contém uma cadeia de caractere de um conjunto de opções enumerado que especifica o tipo de dado primitivo para uma propriedade de metadados. O tipo de dado primitivo determina qual mapa dinâmico disponível em uma ClbPropertySheet contém esse valor de metadados. Os valores dos tipos de dados primitivos a seguir são suportados:
  • Cadeia de caractere
  • Duplo
  • Longo
  • data/hora
  • operadores booleanos

Por padrão, se nenhum valor é especificado no modelo XML PropertySheetType XML, o tipo de dado é igual a string.
multipleEsse tributo opcional contém um valor booleano para determinar se uma propriedade suporta valores múltiplos. O valor-padrão é falso.
indexableEsse atributo opcional contém um valor de operadores booleanos para determinar se essa propriedade deve ser adicionada ao índice. O valor-padrão é falso.
propertyIdEsse atributo de cadeia de caractere necessário contém um identificador para uma propriedade individual dentro de um modelo de folha de propriedade.
propertyNameEsse atributo de cadeia de caractere necessário contém um nome qualificado para a propriedade no repositório backend. Esse nome deve ser definido no clb: prefixo and deve ser exclusivo dentro de um repositório. Ele é a chave no mapa dinâmico para o tipo de dado que contém esse valor da propriedade.
readonlyEsse atributo opcional contém um valor de operadores booleanos que especifica se essa propriedade é um valor somente de leitura no repositório de conteúdo. O valor-padrão é falso.
requiredEsse atributo opcional contém um valor de variáveis booleanas que especifica se essa propriedade é um valor obrigatório no repositório de conteúdo. O valor-padrão é falso.
searchableEsse atributo opcional contém um valor de operadores booleanos que especifica se essa propriedade suporta procura de texto. O valor-padrão é verdadeiro.
maxLengthEsse atributo opcional especifica a restrição de comprimento máximo para propriedades de cadeia de caractere. Se não for especificado, o comprimento máximo padrão é de 252 caracteres.

Além dos atributos, cada elemento <property> pode conter o seguinte:

  • Alguns subelementos opcionais, incluindo um conjunto de elementos <label>, cada um mapeado para um local
  • Um conjunto de elementos <style> fornecendo uma sugestão para a representação visual da propriedade
  • Uma lista de elementos <option> definindo um conjunto de valores possíveis para a propriedade
  • Uma lista de elementos <defaultValue> definindo o valor padrão a ser aplicado à propriedade pelos aplicativos consumidores, caso nenhum seja especificado

Um elemento de propriedade de exemplo é mostrado na Listagem 2.

Listagem 2. Código de elemento <property> de exemplo
<property
  propertyId="prop1"
  dataType="string"
  multiple="false"
  propertyName="clb:p1234"
  readonly="false"
  required="true"
  searchable="false">
<label label="Gender" lang="en" />
  <style name="ibm:selectionType" value="radio" />
  <defaultValue>Female</meta:defaultValue>
  <option>
      <value>Female</meta:value>
      <label label="Female" lang="en" />
  </option>
  <option>
      <value>Male</meta:value>
      <label label="Male" lang="en" />
  </option>
 </property>

Além de criar um tipo de folha de propriedade, pode-se obter uma lista de tipos de folha de propriedade enviando um pedido GET ao URL dos tipos de folha de propriedade. Também, pode-se obter, atualizar ou excluir um tipo de folha de propriedade específico enviando uma operação GET, PUT ou DELETE ao URL da entrada do tipo de folha de propriedade, como a seguir:

http://<host>:<port>/dm/atom/library/<libraryId>
/propertysheettypes/< propertysheettype-id>/entry

Para mais detalhes sobre as operações de tipos de folha de propriedade no Serviço de Documentos REST do Lotus Quickr, consulte o tópico Serviços de Documentos na wiki do Lotus Quickr.

Criando um tipo de documento

Para criar um tipo de documento em uma biblioteca, pode-se enviar um pedido POST ao URL de alimentação do tipo de documento

http://<host>:<port>/dm/atom/library/<libraryId>/documenttypes/feed fornecendo uma entrada Atom do tipo de documento no corpo de um pedido HTTP (veja a Listagem 3).

Listagem 3. Pedido para a criação de um tipo de documento
POST /library/08ca5f0044ab2d6a858eed71ca20d4cf/documenttypes/feed HTTP/1.1
Host: example.com
Content-Type: application/atom+xml
Content-Length: nnnn
Authorization: Basic ...

<entry xml:base="http://example.com/dm/atom/library/
08ca5f0044ab2d6a858eed71ca20d4cf/" xmlns="http://www.w3.org/2005/Atom">
    <id>urn:lsid:ibm.com:td:4e05cb0044f7e4f1937e932188721110</id>
    <td:uuid>4e05cb0044f7e4f1937e932188721110/<td:uuid>
    <category term="documenttype" scheme="tag:ibm.com,2006:td/type" 
    label="documentType"></category>
    <author>
      <uri>uid%3Dquikradm%2Co%3Ddefault+organization</uri>
      <name>quikradm</name>
      <email></email>
    </author>
    <title type="text">word doc</title>
    <updated>2008-04-23T00:40:42.141Z</updated>
    <summary type="text">word Document Type</summary>
    <content type="application/atom+xml" 
    src="library/08ca5f0044ab2d6a858eed71ca20d4cf/documenttype"></content>
    <td:defaultExtension>doc<td:defaultExtension>
    <td:template>209c511448682203a123e3bd1a328f82<td:template>
    <td:propertysheettype>103f553208383112a333b3bd1a319d81
    <td:propertysheettype>    
    <td:propertysheettype>201d33530848122a333b4cd2a419c914
    <td:propertysheettype>    <td:propertysheettype>
    1029c238299d122c332d99f1c491d882<td:propertysheettype>
    <td:versioning>none<td:versioning>
    <td:approvalEnabled>true<td:approvalEnabled>
    <td:approvalType>serial<td:approvalType>    
    <td:approvers>uid%3Dquikradm%2Co%3Ddefault+organization
    <td:approvers>
    <td:expandGroupApprovers>false<td:expandGroupApprovers>
</entry>

O elemento <td:propertysheettype> na entrada contém um Identificador Universal Exclusivo (UUID) do tipo de folha de propriedade a ser usado para esse tipo de documento.

Além de criar um tipo documento, pode-se obter uma lista de tipos de documentos enviando um pedido GET ao URL de alimentação dos tipos de documento. Também, pode-se obter, atualizar ou excluir um tipo documento específico enviando uma operação GET, PUT ou DELETE ao URL da entrada do tipo de documento, como a seguir:

http://<host>:<port>/dm/atom/library/<libraryId>
/documenttypes/< documenttype-id>/entry

Para mais detalhes sobre as operações de tipos de documento no Serviço de Documentos REST do Lotus Quickr, consulte o tópico Serviços de Documentos na wiki do Lotus Quickr.

Criando e atualizando documentos com folhas de propriedade

Após criar o tipo de documento, pode-se fornecer valores para os campos personalizados ao fazer o upload do documento para um tipo de documento específico. Também, pode-se enviar um pedido POST ao URL de alimentação da biblioteca

http://<host>:<port>/dm/atom/library/<libraryId>/feed?doctype=
<documentTypeId>&includePropertySheets=true
ou ao URL de alimentação da pasta

http://<host>:<port>/dm/atom/library/<libraryId>/folder/
<folderId>feed?doctype=<documentTypeId>&includePropertySheets=true
fornecendo uma entrada Atom do documento com valores de campo personalizado no corpo do pedido. Os valores do campo personalizado são descritos pelo elemento <snx:field> contido na entrada Atom do documento. Eles somente surtem efeito se o parâmetro do URL includePropertySheets estiver definido como verdadeiro.

O valor do parâmetro de URL doctype é especificado como o tipo de documento do documento. Os atributos do elemento <snx:field> são descritos na Tabela 2.

Tabela 2. Atributos para o elemento XML <snx:field>
AtributoÉ necessário?Descrição
fidSimDefine o propertyName no espaço de nome clb para essa propriedade de recurso.
nameSimO título do propertysheettype para essa propriedade de recurso.
pstIdSimUUID do propertysheettype para essa propriedade de recurso
typeSimDefine o tipo de campo. Os seguintes valores são suportados:
  • data
  • cadeia de caractere
  • duplo
  • operadores booleanos
  • longo

O código de exemplo na Listagem 4 mostra o pedido HTTP para criar um documento com campos personalizados. Observe que o corpo do pedido é uma entrada Atom que representa um documento e inclui vários elementos <snx:field>.

Listagem 4. Pedido para a criação de um documento com valores de campos personalizados
POST /library/bd03fd75-99c2-46bb-b438-2d151faa7348/
feed?doctype= 4e05cb0044f7e4f1937e932188721110
 &includePropertySheets=true HTTP/1.1
Host: example.com:9080
Content-Type: application/atom+xml; charset="utf-8"
User-Agent: Thingio/1.0

<entry xmlns="http://www.w3.org/2005/Atom">
	<category term="document" scheme="tag:ibm.com,2006:td/type" 
	label="document"></category>
	<summary type="text">Test posting an ATOM document with 
	metadata values</content>
	<title type="text">testPostAtomDocument.txt</title>
	<author>
		<name>mshani</name>
	</author>
<snx:field
  name="pst1"
  fid="clb:ps0"
  pstId="CF2432219C73BB73162A79E0A995292402C7"
  type="date" >
   2008-06-12T04:00:00Z
 </snx:field>
 <snx:field
  name="pst2"
  fid="clb:ps1"
  pstId="F23432219C73BB73162A79E0A9952922520F"
  type="string" >
    string example text
 </snx:field>
 <snx:field
  name="pst3"
  fid="clb:ps2"
  pstId="DD2232219C73BB73162A79E0A99529242C77"
  type="long" >
   2302
 </snx:field>
 <snx:field
  name="pst4"
  fid="clb:ps3"
  pstId="DD2112219C73BB73162A79E0A995292513C8"
  type="double" >
   123.12345
 </snx:field>
 <snx:field
  name="pst5"
  fid="clb:ps4"
  pstId="DD1232219C73BB73162A79E0A99529251D78"
  type="boolean" >
   true
 </snx:field>
</entry>

Pode-se também obter ou atualizar os valores de campos personalizados de documentos enviando uma operação GET ou PUT ao URL de entrada do documento, como a seguir:

http://<host>:<port>/dm/atom/library/<libraryId>/document/< document-id>/entry?includePropertySheets=true

Nesta seção, cobrimos o modelo de programação REST para campos customizados, o que inclui operações de tipos de folha de propriedade e tipos de documento e criação de documentos com elementos <snx:field> que representam valores de campos customizados na entrada Atom. A seguir, mostraremos alguns códigos manipulando campos personalizados em um aplicativo para livraria de exemplo.


Usando campos personalizados em um aplicativo de exemplo

Em nosso cenário real, um aplicativo de livraria online simples, usamos uma biblioteca de documentos para armazenar documentos sobre livros e usamos campos personalizados pra descrever várias propriedades dos livros.

Então, mostramos como criar campos personalizados criando tipos de folha de propriedade e tipos de documento, como criar um documento com campos personalizados e como atualizar os valores nos campos personalizados.

Plano de Fundo

Nossa livraria online usa o Lotus Quickr para gerenciar informações sobre livros. Criamos documentos para cada livro que possuímos e, para descrever completamente as informações do livro, usamos campos personalizados como uma extensão do um documento simples.

Como mencionado acima, descrevemos os campos personalizados no Lotus Quickr criando tipos de folhas de propriedades. As propriedades de nosso tipo de folha de propriedade que descrevem um livro estão listadas na Tabela 3.

Tabela 3. Propriedades no tipo de folha de propriedade
Nome da propriedadeTipo da propriedade
CatálogoCadeia
ISBNCadeia de caractere
PreçoDecimal
Data de publicaçãoData (valor-padrão é 1/1/99)
GêneroOpção única (Ficção/História em Quadrinhos/Biografia)

A Figura 5 mostra a janela Edit Property Sheet em uma UI da Web.

Figura 5. Janela Edit Property Sheet
Edit Property Sheet window

Agora adicionamos campos personalizados ao documento que descreve os livros anexando o tipo de folha de propriedade ao documento do livro. A Figura 6 mostra um exemplo de um documento do livro, com campos personalizados adicionados, em uma UI da Web.

Figura 6. Documento do livro com campos personalizados
Book document with custom fields

Preparando para usar o exemplo de demonstração

Para explicar melhor a implementação, fornecemos um exemplo de demonstração, um programa Java puro, na seção de Downloads deste artigo. Para usar o programa de amostra, primeiro, faça o seguinte:

  1. Crie um local com o modelo de biblioteca no Lotus Quickr.
  2. Obtenha o UUID da biblioteca criada na Etapa 1. Siga estas etapas:

    • Entre na biblioteca em um navegador da Web.
    • Clique em Subscribe to this library no lado direito da página; a alimentação da biblioteca é exibida no navegador.
    • Observe o URL na barra de navegação do navegador, ele se parece com este (o ID entre “library” e “folder” é o que queremos):

      http://<host>:<port>/dm/atom/library/<uuid>/folder/.....

Agora já é possível usar o programa. Follow these steps:

  1. Extraia o anexo example.zip na seção de Downloads deste artigo e edite o arquivo example.properties no diretório target\classes, alterando o valor de server.base.url para

    http://<host>:<port>/dm/atom/library/<uuid>
  2. Altere o valor de user.name e user.password de acordo com as suas configurações do servidor Lotus Quickr.
  3. Certifique de possuir o Java Development Kit (JDK) versão 1.5.0 ou superior instalado em seu sistema e então faça o download do Apache Abdera 0.4.0. O exemplo necessita do Apache Abdera 0.4.0 para construir e analisar os XMLs Atom e emitir operações HTTP.
  4. Para facilitar o uso do Abdera nos aplicativos a seguir, definimos as variáveis de ambiente Microsoft® Windows® ABDERA_HOME e ABDERA_CLASSPATH como mostrado na Listagem 5. Caso esteja usando o Linux® ou o UNIX®, é necessário invocar comandos similares para definir as variáveis de ambiente.
Listagem 5. Definindo as variáveis ABDERA_HOME e ABDERA_CLASSPATH
Set ABDERA_HOME=<The folder where Abdera package is unzipped>
Set ABDERA_CLASSPATH=%ABDERA_HOME%/abdera-0.4.0-incubating.jar;%ABDERA_HOME%/
lib/axiom-api-1.2.5.jar;%ABDERA_HOME%/lib/axiom-impl-1.2.5.jar;%ABDERA_HOME%/lib/
commons-beanutils-1.7.0.jar;%ABDERA_HOME%/lib/commons-codec-1.3.jar;%ABDERA_HOME%/lib/
commons-collections-3.2.jar;%ABDERA_HOME%/lib/commons-httpclient-3.1-rc1.jar;
%ABDERA_HOME%/lib/commons-lang-2.3.jar;%ABDERA_HOME%/lib/commons-logging-1.0.4.jar;
%ABDERA_HOME%/lib/ezmorph-1.0.4.jar;%ABDERA_HOME%/lib/
geronimo-activation_1.0.2_spec-1.1.jar;%ABDERA_HOME%/lib/
geronimo-stax-api_1.0_spec-1.0.1.jar;%ABDERA_HOME%/lib/htmlparser-1.0.5.jar;
%ABDERA_HOME%/lib/jaxen-1.1.1.jar;%ABDERA_HOME%/lib/jetty-6.1.5.jar;
%ABDERA_HOME%/lib/jetty-util-6.1.5.jar;%ABDERA_HOME%/lib/json-lib-2.2.1-jdk15.jar;
%ABDERA_HOME%/lib/servlet-api-2.5-6.1.5.jar;%ABDERA_HOME%/lib/stax-api-1.0.1.jar;
%ABDERA_HOME%/lib/stax-api.jar;%ABDERA_HOME%/lib/wstx-asl-3.2.1.jar;%ABDERA_HOME%/lib/
xalan-2.7.0.jar;%ABDERA_HOME%/lib/xmlsec-1.3.0.jar;.

Executando o exemplo de demonstração

Agora já é possível executar os aplicativos de exemplo.

Aplicativo 1
com.ibm.clb.custom.field.example.CreateCustomFields

Esse aplicativo cria os tipos de folha de propriedade e tipos de documento descritos na seção Plano de Fundo deste artigo. Para executar o aplicativo, vá até o diretório target\classes e insira o comando a seguir:

java –cp “%ABDERA_CLASSPATH%” com.ibm.clb.custom.field.example.CreateCustomFields

Se tudo correr bem, o aplicativo imprime informações sobre pedidos e respostas trocados entre seu cliente e o servidor Lotus Quickr. Após sair do aplicativo, ele salva o UUID do tipo de folha de propriedade e tipo de documento que ele criou no arquivo example.properties. Ele deve se parecer com este:

created.pst.id=53791f0040f5e84eba81faa681ef10bf
created.doctype.id=bc6b918040f5e864ba82faa681ef10bf

NOTE: Caso tenha importado o projeto de exemplo para o Eclipse ou Ambiente de Desenvolvimento Integrado (IDE) Java, pode-se ter que sincronizar manualmente o arquivo example.properties de bin/classes (ou onde as classes de construção residirem) para src/ (ou onde o código de origem residir).

Pode-se também efetuar o login no servidor Lotus Quickr a partir de um navegador da Web para verificar o tipo de folha de propriedade e o tipo de documento criados.

Aplicativo 2
com.ibm.clb.custom.field.example.CreateDocumentWithCustomFields

Esse aplicativo cria um documento de entrada com o tipo de folha de propriedade e tipo de documento criado:

java –cp “%ABDERA_CLASSPATH%”
com.ibm.clb.custom.field.example.CreateDocumentWithCustomFields

NOTE: Deve-se assegurar de que as propriedades created.pst.id e created.doctype.id já estão no arquivo example.properties antes de executar esse comando.

Esse aplicativo também imprime mensagens enviadas e recebidas pelo servidor Lotus Quickr. A última linha de mensagens impressas nos diz o UUID do documento que criamos:

document uuid: ce8f7000411626fdbab3faa681ef10bf

Anote o UUID; ele é usado como a entrada para o aplicativo de exemplo a seguir.

Aplicativo 3
com.ibm.clb.custom.field.example.UpdateDocumentWithCustomFields

Esse aplicativo atualiza os campos personalizados de um documento existente, tomando o UUID de um documento como sua entrada:

java –cp “%ABDERA_CLASSPATH%”
com.ibm.clb.custom.field.example.UpdateDocumentWithCustomFields
<document-uuid>

Nas seções a seguir, discutiremos os detalhes de programação desses aplicativos de exemplo.

Criando campos personalizados

Para criar campos personalizados, primeiramente devemos criar um tipo de folha de propriedade. Como mencionado acima, para esta etapa, necessitamos POST uma entrada Atom que represente um tipo de folha de propriedade para o URL de alimentação do tipo de folha de propriedade.

Como descrito na seção Gerenciando campos personalizados usando o modelo de programação REST, o elemento chave na entrada do tipo de folha de propriedade é o XML propertySheetTemplate no elemento de conteúdo da entrada.

Por exemplo, para o tipo de folha de propriedade mencionado na subseção Plano de Fundo, o XML propertySheetTemplate se parece com o mostrado na Listagem 6.

Listagem 6. Documento XML PropertySheetTemplate
<?xml version="1.0" encoding="UTF-8" ?>
  <meta:propertySheetTemplate xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
  xmlns:clb="http://content.ibm.com/clb/1.0" xmlns:
  meta="http://metadata.model.xsd.clb.content.ibm.com/1.0">
  <meta:property xsi:type="meta:ClbPropertyType" dataType="string" 
  maxLength="2048" multiple="false" propertyId="clb:ps1" 
  propertyName="clb:p_a6aa8d78-bc9e-4a35-a243-000aaaa8af12" readonly="false" 
  required="false" searchable="true">
    <meta:label label="Catalog" lang="en" />
    <meta:style name="ibm:textVariant" value="medium" />
  </meta:property>
    <meta:property xsi:type="meta:ClbPropertyType" dataType="string" 
    maxLength="254" multiple="false" propertyId="clb:ps2" 
    propertyName="clb:p_f4179b4b-9c29-45ea-a18b-3e507002015d" readonly="false" 
    required="false" searchable="true">
    <meta:label label="ISBN" lang="en" />
    <meta:style name="ibm:textVariant" value="medium" />
  </meta:property>
  
  <meta:property xsi:type="meta:ClbPropertyType" dataType="double" 
  multiple="false" propertyId="clb:ps3"
propertyName="clb:p_73020b22-ea33-4c14-b8dd-68791bdec517" readonly="false" 
required="false" searchable="true">
    <meta:label label="Price" lang="en" />
  </meta:property>

  <meta:property xsi:type="meta:ClbPropertyType" dataType="dateTime" 
  multiple="false" propertyId="clb:ps4" 
  propertyName="clb:p_c5c61619-44d7-4a12-bbba-9c5c7e245958" readonly="false" 
  required="false" searchable="true">
    <meta:label label="Publish Date" lang="en" />
    <meta:style name="ibm:dateVariant" value="date" />
    <meta:defaultValue>1999-01-01T00:00:00Z</meta:defaultValue>
  </meta:property>

  <meta:property xsi:type="meta:ClbPropertyType" dataType="string" 
  multiple="false" propertyId="clb:ps5" 
  propertyName="clb:p_946e09da-2e11-4bf8-9139-cb49c713bbe4" readonly="false" 
  required="false" searchable="true">
    <meta:label label="Genre" lang="en" />
    <meta:style name="ibm:selectionType" value="radio" />
    <meta:defaultValue>fiction</meta:defaultValue>
    <meta:option>
      <meta:value>fiction</meta:value>
      <meta:label label="Fiction" lang="en" />
    </meta:option>
    <meta:option>
      <meta:value>comic</meta:value>
      <meta:label label="Comic" lang="en" />
    </meta:option>
    <meta:option>
      <meta:value>biography</meta:value>
      <meta:label label="Biography" lang="en" />
    </meta:option>
  </meta:property>
</meta:propertySheetTemplate>

Necessitamos preparar um documento XML assim em código Java e inseri-lo no conteúdo de entrada do tipo de folha de propriedade. Para simplificar, construímos, em nosso exemplo, esse documento XML usando concatenação de cadeia de caractere; no entanto, em um projeto real, pode-se ter que usar um Modelo de Objeto de Documento (DOM) ou uma API XML similar.

O fragmento de código usado para construir o documento XML é mostrado na Listagem 7. Todo o código é da classe com.ibm.clb.custom.field.example.CreateCustomFields no código de origem de nosso exemplo.

Listagem 7. Código para a construção do XML propertySheetTemplate
// start building propertySheetTemplate
StringBuilder pstTpl = new StringBuilder();
// add xml root tag start
pstTpl.append("<?xml version=\"1.0\" encoding=\"UTF-8\"?>
<meta:propertySheetTemplate xmlns:xsi=\"http://www.w3.org/2001/XMLSchema-instance\" 
xmlns:clb=\"http://content.ibm.com/clb/1.0\" xmlns:
meta=\"http://metadata.model.xsd.clb.content.ibm.com/1.0\">");
pstTpl.append(new MetaPropertyElementBuilder().setDataType("string").
setMaxLength("2048").setPropertyId("clb:ps1").setLabelName("Catalog").
setStyleName("ibm:textVariant").setStyleValue("medium").build());
// ...similarly add other properties...

// add xml root tag end
pstTpl.append("</meta:propertySheetTemplate>");

A classe do utilitário MetaPropertyElementBuilder é usada para construir um elemento <meta:property> no código XML. Nessa classe, vários atributos são agregados para formarem um elemento <meta:property> válido. Observe que o atributo propertyName é gerado de maneira aleatória usando a classe java.util.UUID.

Quando o XML propertySheetTemplate estiver pronto, colocamo-lo em uma entrada ATOM, mas antes, devemos usar o Apache Abdera para gerar a entrada ATOM. Follow these steps:

  1. Gere uma entrada vazia e, então, adicione <atom:category> para declarar que ela representa um tipo de folha de propriedade:

    Entry entry = abdera.newEntry();
    entry.addCategory("tag:ibm.com,2006:td/type", "propertySheetType",
    "propertySheetType");
  2. Defina o título do tipo da folha de propriedade:

    String pstTitle = "custom-fields-example-" + System.currentTimeMillis();
    entry.setTitle(pstTitle);
  3. Defina o XML propertySheetTemplate gerado para o conteúdo da entrada:

    entry.setContent(pstTpl.toString());

    Nesta etapa, o Abdera executa algumas manipulações de cadeia de caractere XML de escape. Caso imprima a entrada neste momento, ela parecerá estranha.

  4. Finalmente, preparamos o pedido HTTP e o postamos (POST) no URL de alimentação do tipo de folha de propriedade:

    RequestOptions opt = new RequestOptions();
    opt.setUseChunked(false);
    opt.setContentType("application/atom+xml");
    ClientResponse response = client.post(loader.getPstFeedUrl(), entry, opt);

A chamada será bem sucedida se tudo estiver OK com o servidor, que responde com 201 Created. Pode-se ler o código de status no objeto de resposta recebido da chamada HTTP POST. Pode-se também obter a entrada para o tipo de folha de propriedade criada a partir da resposta:

Entry retPstEntry = (Entry) response.getDocument().getRoot();
String retPstId = Utils.getUuidFromEntry(retPstEntry);

Após criar o tipo de folha de propriedade, devemos adicioná-la ao tipo de documento, para que possamos usar esse tipo de folha de propriedade como campos personalizados em um documento. Essa etapa é feita usando uma chamada HTTP POST para o URL de alimentação do tipo de documento.

É fácil criar tal tipo de documento: Crie uma entrada Atom e insira o UUID do tipo de folha de propriedade retornado como o elemento <td:propertySheetType>, como mostra a Listagem 8.

Listagem 8. Crie uma entrada Atom de tipo de documento e defina o tipo de folha de propriedade
entry = abdera.newEntry();
entry.addCategory("tag:ibm.com,2006:td/type", "documentType", "documentType");
String docTypeTitle = "doctype-example-" + System.currentTimeMillis();
entry.setTitle(docTypeTitle);
// extension elements for doctype
ExtensibleElement el = entry.addExtension("urn:ibm.com/td", "propertySheetType", "td");
el.setText(retPstId);

The entry is ready. Precisamos postá-la (POST) no servidor para criá-la.

Agora, criamos um tipo de folha de propriedade e um tipo de documento contendo-o. Nossos campos personalizados estão prontos para serem usados.

Criando um documento com campos personalizados

Como já possuímos um tipo de folha de propriedade para descrever nossos campos personalizados e o adicionamos ao tipo de documento, podemos criar documentos com os campos personalizados.

Criaremos um documento usando um comando HTTP POST para um URL de alimentação de biblioteca e demonstraremos a criação de uma Entrada Atom com campos personalizados como exemplo. O código nas etapas a seguir vem de com.ibm.clb.custom.field.example.CreateDocumentWithCustomFields.

  1. Comece construindo uma entrada de documento simples:

    Entry entry = abdera.newEntry();
    entry.addCategory("tag:ibm.com,2006:td/type", "document", "document");
    entry.setTitle("document-example-" + System.currentTimeMillis());
    entry.setSummary("A test piece of entry.");
  2. A seguir, diga ao servidor para anexar o tipo de documento ao documento. Lembre-se de que podemos executar essa etapa anexando o parâmetro documenttype ao URL ou adicionando um elemento à entrada do documento como um elemento <td:documenttype> . Aqui, usamos o último método:

    ExtensibleElement el = entry.addExtension("urn:ibm.com/td", "documenttype", "td");
    el.setText(loader.getCreatedDoctypeId());

    Agora, o documento está anexado com os campos personalizados que definimos.

    Podemos, então, dar valores a cada campo adicionando um elemento <snx:field> à entrada do documento. Como o código XML propertySheetTemplate em nosso exemplo, construímos <snx:field> por concatenação de cadeia de caractere. Novamente, para projetos reais, considere o uso de APIs XML, como DOM.

  3. Primeiro, encontramos as informações de propriedade do XML propertySheetTemplate designando seu ID de propriedade:

    ExtensibleElement customFieldEl =
    Utils.findCustomFieldElementByPropertyId(pstTplEl, "clb:ps1");
    onde o método do utilitário findCustomFieldElementByPropertyId() busca uma propriedade por seu ID de propriedade em todas as propriedades criadas em propertySheetTemplate.
  4. Finalmente, criamos o elemento <snx:field> colocando informações de propriedade e de tipo de folha de propriedade juntas como necessário (consulte a Tabela 2):

    new SnxFieldBuilder(entry).setFid(customFieldEl.getAttributeValue
    ("propertyName")).setName(pstName).setPstId(pstId).setType
    ("string").setValue("1, prelude\n2, middle\n3, end. " +
    System.currentTimeMillis()).build();

É isso que necessitamos fazer para construir a entrada Atom representando o documento com campos personalizados. A entrada do documento completa é mostrada na Listagem 9.

Listagem 9. Entrada de documento postada (POST) com <snx:field>
<entry xmlns="http://www.w3.org/2005/Atom" xmlns:td="urn:ibm.com/td" 
xmlns:snx="http://www.ibm.com/xmlns/prod/sn">
  <category term="document" scheme="tag:ibm.com,2006:td/type" 
  label="document" />
  <title type="text">document-example-1263702859296</title>
  <td:documenttype>62a16d0041064cd6ba95faa681ef10bf</td:documenttype>
  <summary type="text">A test piece of entry.</summary>
  <snx:field fid="clb:p_a6aa8d78-bc9e-4a35-a243-000aaaa8af12" 
  name="custom-fields-example-1263378081261" pstId="f0c0280041064cc3ba94faa681ef10bf" 
  type="string">1, prelude
2, middle
3, end. 1263702859359</snx:field>
  <snx:field fid="clb:p_f4179b4b-9c29-45ea-a18b-3e507002015d" 
  name="custom-fields-example-1263378081261" pstId="f0c0280041064cc3ba94faa681ef10bf" 
  type="string">1-2-3-4</snx:field>
  <snx:field fid="clb:p_73020b22-ea33-4c14-b8dd-68791bdec517" 
  name="custom-fields-example-1263378081261" pstId="f0c0280041064cc3ba94faa681ef10bf" 
  type="double">12.34</snx:field>
  <snx:field fid="clb:p_c5c61619-44d7-4a12-bbba-9c5c7e245958" 
  name="custom-fields-example-1263378081261" pstId="f0c0280041064cc3ba94faa681ef10bf" 
  type="date">2010-01-07T20:32:00Z</snx:field>
  <snx:field fid="clb:p_946e09da-2e11-4bf8-9139-cb49c713bbe4" 
  name="custom-fields-example-1263378081261" pstId="f0c0280041064cc3ba94faa681ef10bf" 
  type="string">comic</snx:field>
</entry>

The entry is ready. Nós a postamos (POST) no servidor usando um código similar ao código usado ao postar os tipos de folha de propriedade ou tipos de documento. O servidor responde com uma mensagem 201 Created, caso a criação tenha sido bem sucedida. Pode-se obter uma entrada do documento criado do objeto de resposta.

NOTE: Esse exemplo mostrou como criar um documento usando uma entrada Atom; no entanto, com serviço de documento REST do Lotus Quickr, podemos também criar um documento com campos personalizados fazendo o upload do conteúdo binário do documento.

Para executar essa tarefa, primeiro, faça o upload do binário do documento com o tipo de documento adequado e, então, atualize o documento com <snx:field>. Para mais detalhes sobre como criar um documento fazendo o upload do conteúdo binário, veja o tópico Serviços de Documentos na wiki do Lotus Quickr.

http://www-10.lotus.com/ldd/lqwiki.nsf/dx/documents-services

Atualizando um documento com campos personalizados

A atualização de um documento com campos personalizados é bem similar à criação deles. Para executar essa tarefa, construa uma entrada de documento e a envie através de um comando HTTP PUT ao URL de entrada do documento, como em:

http://<host>:<port>/dm/atom/library/<lib-id>
/document/<document-id>/entry

Aqui, obtemos uma entrada de documento existente com campos personalizados e, então, atualizamos os campos. Também é possível construir campos começando do zero, se o UUID do documento correto estiver incluído na entrada do documento.

Para obter a entrada do documento, usamos o comando HTTP GET para o URL de entrada do documento:

ClientResponse response = client.get(loader.getDocumentEntryUrl(docId));
Entry docEntryWithPropertySheet = (Entry) response.getDocument().getRoot();

Como na criação do documento, atualizamos os campos personalizados colocando-os em uma entrada de documento como <snx:field>:

ExtensibleElement customFieldEl =
Utils.findCustomFieldElementByPropertyId(pstTplEl, "clb:ps3");
new SnxFieldBuilder(docEntry).setFid(customFieldEl.getAttributeValue
("propertyName")).setName(pstName).setPstId(pstId).setType
("double").setValue("15.57").build();

É necessário incluir somente os campos atualizados na entrada do documento Atom ao atualizar o documento; no fragmento de código anterior, atualizamos o campo Preço (Price).

Em seguida, colocamos (PUT) essa entrada atualizada no servidor:

RequestOptions opt = new RequestOptions();
opt.setUseChunked(false);
opt.setContentType("application/atom+xml");
response = client.put(loader.getDocumentEntryUrlWithLockTrue(docId), docEntry, opt);

O servidor responde com uma mensagem 200 OK se a atualização for bem sucedida e se a entrada de documento atualizada tiver sido incluída na resposta.


Conclusão

Neste artigo, introduzimos o conceito de suporte a campos personalizados no serviço de documento REST do Lotus Quickr 8.1.1. Discutimos o modelo de programação no serviço de documento REST e demonstramos como usá-lo através de um aplicativo de livraria simples, seguindo as seguintes etapas:

  • Criando um tipo de folha de propriedade que inclua campos personalizados
  • Criando um tipo de documento que seja associado a um tipo de folha de propriedade
  • Criando um documento com campos personalizados associando um tipo de documento e especificando valores de propriedades em uma entrada Atom
  • Atualizando campos personalizados de um documento

Baseando-se no suporte a campos personalizados fornecido pelo serviço de documento REST, os usuários podem desenvolver seus próprios aplicativos que podem trabalhar com campos customizados no Lotus Quickr.


Download

DescriçãoNomeTamanho
Código de amostraexample.zip28KB

Recursos

Comentários

developerWorks: Conecte-se

Los campos obligatorios están marcados con un asterisco (*).


Precisa de um ID IBM?
Esqueceu seu ID IBM?


Esqueceu sua senha?
Alterar sua senha

Ao clicar em Enviar, você concorda com os termos e condições do developerWorks.

 


A primeira vez que você entrar no developerWorks, um perfil é criado para você. Informações no seu perfil (seu nome, país / região, e nome da empresa) é apresentado ao público e vai acompanhar qualquer conteúdo que você postar, a menos que você opte por esconder o nome da empresa. Você pode atualizar sua conta IBM a qualquer momento.

Todas as informações enviadas são seguras.

Elija su nombre para mostrar



Ao se conectar ao developerWorks pela primeira vez, é criado um perfil para você e é necessário selecionar um nome de exibição. O nome de exibição acompanhará o conteúdo que você postar no developerWorks.

Escolha um nome de exibição de 3 - 31 caracteres. Seu nome de exibição deve ser exclusivo na comunidade do developerWorks e não deve ser o seu endereço de email por motivo de privacidade.

Los campos obligatorios están marcados con un asterisco (*).

(Escolha um nome de exibição de 3 - 31 caracteres.)

Ao clicar em Enviar, você concorda com os termos e condições do developerWorks.

 


Todas as informações enviadas são seguras.


static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=80
Zone=Lotus
ArticleID=475513
ArticleTitle=Gerenciando campos personalizados usando o serviço de documentos REST nos serviços IBM Lotus Quickr 8.1.1 para WebSphere Portal
publish-date=02232010