Guia de Consulta de Repositórios para a Integração de Modelos Lógicos

Para facultar total apoio para os modelos lógicos, um fornecedor de repositórios pode executar os seguintes passos:

  1. Contribuir com as operações de repositórios adequadas para os elementos que se adaptam a ResourceMapping.
  2. Assegurar que as operações executadas nas correlações de recursos incluem todos os elementos de modelos e recursos adequados através da utilização de ISynchronizationScope e da API de suporte.
  3. Permitir que os fornecedores de modelos participem nas intercalações sem cabeçalho através da interface IMergeContext e da API de suporte.
  4. Permitir que os fornecedores de modelos participem nas pré-visualizações da intercalação através da utilização de teamContentProviders para os modelos envolvidos na intercalação. É facultada uma classe ModelSynchronizeParticipant para auxiliar a gestão da relação entre o conteúdo do modelo, o contexto da intercalação e o enquadramento de Comparação.
  5. Facultar acesso ao histórico dos ficheiros do espaço de trabalho através da API IFileHistoryProvider
  6. Facultar acesso às configurações remotas através da utilização da API do Sistema de Ficheiros do Eclipse no plug-in org.eclipse.core.filesystem e ligá-las aos projectos do espaço de trabalho através de ProjectSetCapability
  7. Suportar decorações de elementos de modelos lógicos ao facultar um Subscriber do espaço de trabalho para utilizar com a API SynchronizationStateTester.

As secções seguintes descrevem mais detalhadamente cada um destes pontos. O plug-in org.eclipse.team.examples.filesystem contém um exemplo que ilustra vários pontos. Poderá dar saída ao projecto do repositório CVS e utilizá-lo como referência para ler este guia de iniciação. Renúncia de Responsabilidade: O código fonte nos plug-ins exemplo poderá ser alterado com o tempo. Para obter uma cópia que corresponde ao que é utilizado neste exemplo, pode verificar o projecto utilizando o identificador da versão 3.2 (provavelmente o R3_2) ou um identificador da data de 28 de Junho de 2006.

Acções de Contribuição para as Correlações de Recursos

A API Básica de Correlações de Recursos

A API de correlação de recursos consiste nas seguintes classes:

Existem dois tipos de plug-ins que deverão ter algum interesse nas correlações de recursos. Os plug-ins que facultam um modelo que consiste ou persiste nos recursos do espaço de trabalho e os plug-ins que pretendem executar operações nos recursos. O caso anterior será abordado no guia de consulta de modelos e o último caso será abordado da secção seguinte.

Correlações de Recursos e Contribuições de Objectos

Os plug-ins que contribuem com extensões para pontos de extensão adaptáveis terão de efectuar duas alterações para suportar os novos APIs ResourceMapping:

  1. Actualizar qualquer objectContributions do ponto de extensão popupMenus no ficheiro plugin.xml para destinar o ResourceMapping em vez do IResource (naqueles em que seja adequado).
  2. Actualizar as acções de modo a trabalhar no ResourceMapping em vez de no IResource e respeitar as restrições de profundidade facultadas nas travessias.

Os plug-ins que adicionam contribuições de objectos ao IResource podem agora adicioná-las a ResourceMapping, se a acção poder aplicar vários recursos. Em seguida é apresentado um fragmento XML que contribui com uma acção de menu para objectos que se adaptam às correlações de recursos:

   <extension
       point="org.eclipse.ui.popupMenus">
     <objectContribution
            objectClass="org.eclipse.core.resources.mapping.ResourceMapping"
            adaptable="true"
            id="org.eclipse.team.ccvs.ui.ResourceMapperContributions">
<enablement>
<adapt type="org.eclipse.core.resources.mapping.ResourceMapping">
<test
property="org.eclipse.core.resources.projectPersistentProperty"
args="org.eclipse.team.core.repository,org.eclipse.team.cvs.core.cvsnature" />
</adapt>
</enablement>
<action
label="%UpdateAction.label"
definitionId="org.eclipse.team.cvs.ui.update"
class="org.eclipse.team.internal.ccvs.ui.actions.UpdateAction"
tooltip="%UpdateAction.tooltip"
menubarPath="team.main/group2"
id="org.eclipse.team.cvs.ui.update">
</action>
...
</objectContribution>
</extension>

As contribuições para a ResourceMapping serão aplicadas automaticamente a objectos que se adaptem a IResource. Esta associação transitiva é processada pela Área de Trabalho. A filtragem das contribuições para correlações de recursos pode ser efectuada através da utilização das expressões de activação. Foi adicionada uma expressão para filtrar objectos por propriedade de persistência do projecto para permitir que os menus dos fornecedores de repositórios sejam apresentados nos projectos correlacionados com os respectivos repositórios.

As acções que contribuíram para a classe ResourceMapping class receberão uma selecção que contém uma ou mais ResourceMappings. É da responsabilidade das acções traduzir a correlação de recursos num conjunto de recursos nos quais será efectuada a operação. Este procedimento pode ser efectuado ao chamar getTraversals para obter as travessias da correlação. As travessias são utilizadas para permitir que os clientes de uma travessia optimizem as operações com base na profundidade dos recursos a serem atravessados. Um cliente pode atravessar o recurso manualmente ou pode utilizar o recursos e a profundidade como entrada de dados numa operação que a acção delega para efectuar o trabalho. Por exemplo, se o utilizador executar uma actualização de CVS num pacote java e a correlação de recursos do pacote java se correlaciona com uma pasta de profundidade um, o CVS irá emitir um comando adequado ("cvs update -l" para quem tiver curiosidade) que irá executar uma actualização superficial da pasta que o pacote representa.

Apesar de ser possível obter um conjunto de travessias directamente a partir das correlações de recursos seleccionadas, existem relações de modelos (ou relações de repositórios) que poderão necessitar da inclusão de recursos adicionais ou de elementos de modelos numa operação. A secção seguinte descreve o modo como assegurar que todos os recursos necessários estão incluídos numa operação

Âmbito da Operação

Nas operações da equipa, as correlações seleccionadas necessitam de ser traduzidas em conjuntos de correlações nas quais será efectuada a operação. Este processo envolve a consulta de todos os fornecedores de modelos para assegurar que são incluídos nas operações efectuadas nos recursos que correspondem às regras de activação. O termo utilizado para descrever o conjunto completo de correlações de recursos nos quais será efectuada a operação é scope. A seguinte API foi facultada para:

O método initialize(IProgressMonitor) da classe SynchronizationScopeManager processa todo o processo de conversão de um conjunto de entrada de correlações de recursos para um conjunto de correlações nas quais é necessário efectuar uma operação, bem como um conjunto completo de travessias que engloba estas correlações. Um fornecedor de repositórios pode personalizar o processo ao:

  1. Facultar um RemoteResourceMappingContext para utilizar ao obter travessias de recursos a partir de correlações de recursos
  2. Substituir o SynchronizationScopeManager para personalizar o processo de gestão do âmbito do modo requerido

As duas secções seguintes descrevem estes pontos de forma mais detalhada.

Contexto de Correlação de Recursos Remotos

Para garantir que todos os recursos necessários são incluídos numa operação da equipa, o fornecedor de modelos poderá necessitar da capacidade de ver o estado de um ou mais recursos contidos no repositório. Alguns modelos poderão não necessitar desta opção. Por exemplo, um pacote java consiste num contentor visitado numa profundidade de um, independentemente do estado remoto do modelo. Dado isto, um fornecedor de repositórios pode facilmente determinar que as eliminações de saída deverão ser incluídas durante a consolidação ou que as adições de entrada deverão ser incluídas durante a actualização. Contudo, os recursos que constituem alguns modelos lógicos poderão ser alteradas com o decorrer do tempo. Por exemplo, os recursos que constituem um elemento de modelos pode depender dos conteúdos de um ficheiro de manifesto (ou de outro mecanismo semelhante). Para que a correlação de recursos resulte na travessia adequada, terá de aceder aos conteúdos remotos do ficheiro de manifesto (caso estes sejam diferentes dos conteúdos locais) para que possa verificar se é necessário incluir recursos adicionais. Estes recursos adicionais poderão não existir no espaço de trabalho, mas o fornecedor de repositórios saberá assegurar que existem quando a acção seleccionada for executada.

Para suportar estes modelos mais complexos, poderá ser transmitido um RemoteResourceMappingContext para o método ResourceMapping#getTraversals. Quando é facultado um contexto, a correlação pode utilizá-lo para assegurar que todos os recursos necessários estão incluídos na travessia. Se um contexto não for facultado, a correlação pode pressupor que apenas o estado local é de interesse.

O contexto de correlações de recursos remotos faculta três consultas básicas:

A resposta à primeira questão colocada acima depende do tipo de operação a ser executada. Geralmente, as actualizações e as intercalações são em três sentidos enquanto que as comparações e as operações de substituição (pelo menos no caso de CVS) são em dois sentidos.

A API da Equipa do Eclipse inclui uma classe Subscriber que define uma API para facultar o estado de sincronização entre o espaço de trabalho local e um servidor remoto. É facultado um SubscriberResourceMappingContext para utilizar um Subscriber que permite aceder ao estado remoto necessário. Os clientes que contêm um Subscriber não necessitam de trabalho adicional para obter um contexto de correlação de recursos.

Subclassificação de SynchronizationScopeManager

A classe SynchronizationScopeManager pode ser subclassificada para personalizar a geração do âmbito e o processo de gestão. Os dois motivos principais para subclassificar o gestor de âmbito são:

  1. O fornecedor de repositórios necessita de incluir recursos adicionais devido a algumas relações do nível dos repositórios (por exemplo, alteração de conjunto). Esta acção pode ser efectuada ao substituir o método adjustInputTraversals(ResourceTraversal[]).
  2. A sincronização tem um ciclo de vida longo (por exemplo, vista versus caixa de diálogo Sincronizar) e necessita o potencial para reagir às alterações do âmbito. A interface ISynchronizationScopeParticipant define a API que os fornecedores de modelos podem utilizar para participar no processo de gestão do âmbito. A classe SubscriberScopeManager é uma subclasse baseada no Subscriber do SynchronizationScopeManager que envolve os participantes no processo de gestão do âmbito. Um exemplo do motivo da necessidade deste tipo de processo são os conjuntos de trabalho. Se um conjunto de trabalho for uma das correlações de recursos num âmbito, o conjunto de travessias abrangido pelo âmbito iria aumentar se os recursos fossem adicionados ao conjunto de trabalho.

Intercalação baseada em Modelos

O tipo principal de operações de repositórios que requer a participação de modelos está a ser intercalado. na maioria dos casos, os modelos apenas necessitam de participar ao nível do ficheiro. Para este efeito, a API IStorageMerger foi introduzida de modo a permitir que os fornecedores de modelos contribuíssem com intercalações que deveriam ser utilizadas para intercalar ficheiros de uma determinada extensão ou de um determinado tipo de conteúdo. Contudo, em alguns casos, os modelos poderão necessitar de contexto adicional para que possam participar correctamente numa intercalação. Por conseguinte, são introduzidas as APIs IResourceMappingMerger e IMergeContext.

As operações de intercalação são activadas pelas operações associadas a um fornecedor de repositórios. Contudo, quando uma operação de tipo de intercalação é requerida pelo utilizador, o fornecedor de repositórios necessita de envolver os fornecedores de modelos no processo de intercalação de modo a assegurar que esta não danifica o modelo.

Existem duas partes principais da API do fornecedor de repositórios relacionadas com o suporte de intercalação baseado no modelo.

  1. A API para descrever o estado de sincronização dos recursos envolvidos na intercalação.
  2. A API para permitir que os fornecedores de modelos intercalem os elementos de modelos.
As secções seguintes descrevem estas duas partes.

A API para a Descrição do Estado de Sincronização

Um aspecto importante da intercalação com base no modelo é a API utilizada para comunicar o estado de sincronização dos recursos envolvidos no fornecedor de modelos. As seguintes interfaces são utilizadas para descrever o estado de sincronização:

As classes abstractas são facultadas para todas estas interfaces com a convenção que os nomes das classes correspondem aos nomes das interfaces com o prefixo "I" removido. A única classe que os fornecedores de repositórios têm de substituir é a classe ResourceDiff, para que as revisões de ficheiros antes e depois sejam facultadas.

A API para a Intercalação de Modelos

A interface IMergeContext expande o contexto de sincronização com os métodos adicionais que suportam a intercalação. Os métodos de chamada de retorno existem para:

É facultada uma classe abstracta MergeContext que contém implementações predefinidas para grande parte do comportamento de intercalação e que utiliza o IStorageMerger para executar intercalações em três sentidos. É também facultada uma classe SubscriberMergeContext que processa o preenchimento e a gestão da descrição do estado de sincronização associado ao contexto de intercalação.

É facultada uma classe de operação ModelMergeOperation que utiliza a API IResourceMappingMerger para executar uma operação de intercalação com base no modelo. As subclasses necessitam de substituir o método initializeContext(IProgressMonitor)para devolverem um contexto de intercalação. A operação utiliza este contexto numa tentativa de efectuar uma intercalação com base no modelo sem cabeçalho. Se existirem conflitos, a pré-visualização da intercalação compete à subclasse. Como será apresentado na secção seguinte, existe um ModelParticipantMergeOperation que faculta capacidades de pré-visualização através da utilização de um ModelSynchronizeParticipant.

Conteúdo do Modelo nos Visualizadores da Equipa

O suporte para a apresentação de modelos lógicos numa operação da equipa é facultado através da utilização do enquadramento do Navegador Comum introduzido no Eclipse 3.2. Os modelos lógicos podem associar uma extensão de conteúdo a um fornecedor de modelos através da utilização do ponto de extensão org.eclipse.team.ui.teamContentProvider. Os fornecedores de equipas acedem a este fornecedores de conteúdos através do ITeamContentProviderManager.

Existem vários locais em que o fornecedor de equipas pode pretender apresentar modelos lógicos:

O ModelSynchronizeParticipant faculta a integração na vista Sincronizar ou qualquer contentor que pode apresentar iSynchronizePages. O participante utiliza as capacidades do participante de sincronização pré-existentes e as capacidades do Navegador Comum para permitir que os fornecedores de equipas e os modelos personalizem a barra de ferramentas, o menu contextual e outros aspectos da pré-visualização de intercalação. O ModelSynchronizeParticipant faculta o seguinte:

Em seguida, é apresentada uma lista de verificação dos passos utilizados para personalizar um participante de sincronização de modelo de um determinado fornecedor de Equipas:

Os seguintes fragmentos XML ilustram o modo como a classe do participante de CVS é registada e o modo como é definido o respectivo visualizador.

   <extension
point="org.eclipse.team.ui.synchronizeParticipants">
<participant
            name="CVS"
            icon="$nl$/icons/full/eview16/cvs_persp.gif"

class="org.eclipse.team.internal.ccvs.ui.mappings.WorkspaceModelParticipant"
            id="org.eclipse.team.cvs.ui.workspace-participant">
	</participant>
   </extension>
   
   <extension point="org.eclipse.ui.navigator.viewer">
       <viewer
viewerId="org.eclipse.team.cvs.ui.workspaceSynchronization">
<popupMenu
                allowsPlatformContributions="false"
                id="org.eclipse.team.cvs.ui.workspaceSynchronizationMenu">
             <insertionPoint name="file"/>
             <insertionPoint name="edit" separator="true"/>
             <insertionPoint name="synchronize"/>
             <insertionPoint name="navigate" separator="true"/>
             <insertionPoint name="update" separator="true"/>
             <insertionPoint name="commit" separator="false"/>
             <insertionPoint name="overrideActions" separator="true"/>
             <insertionPoint name="otherActions1" separator="true"/>
             <insertionPoint name="otherActions2" separator="true"/>
             <insertionPoint name="sort" separator="true"/>
             <insertionPoint name="additions" separator="true"/>
             <insertionPoint name="properties" separator="true"/>
          </popupMenu>
	</viewer>
   </extension>

Histórico de Ficheiros

Uma API do histórico de ficheiros foi adicionada para permitir que os modelos tenham acesso ao histórico de ficheiros. A API do histórico de ficheiros consiste nas seguintes interfaces:

Foi adicionada uma vista genérica Histórico de ficheiros com esta API. Isto irá permitir que os fornecedores de Equipas apresentem o respectivo histórico de ficheiros/recursos numa vista partilhada e permite também que os modelos utilizados para apresentar o histórico dos elementos de modelos para os elementos que não se correlacionam directamente com os ficheiros. A vista Histórico é uma vista baseada numa página que obtém uma página para o elemento seleccionado da seguinte forma:

Capacidade de Conjuntos de Projectos

Os métodos foram adicionados a ProjectSetCapability para suportar a tradução entre uma cadeia de referência, utilizada para identificar uma correlação entre um projecto e o conteúdo remoto e os URIs, que identificam um esquema de sistema de ficheiros registado com o ponto de extensão org.eclipse.core.filesystem.filesystems. Os fornecedores de equipas têm a opção de facultar suporte para esta acção de modo a permitir que os modelos lógicos executem procuras remotas e carregamentos de projectos.

Decorar Elementos de Modelos

Os fornecedores de equipas podem decorar elementos de modelos ao converter os respectivos decoradores leves para que funcionem para as correlações de recursos do mesmo modo que as contribuições de objectos são convertidas para funcionarem para as correlações de recursos. Contudo, existe um aspecto de decoração de elementos de modelos lógicos que é problemático. Se um elemento de modelos não contiver uma correlação de um-para-um com um recursos, o elemento de modelos poderá não receber uma actualização de etiquetas quando os recursos subjacentes forem alterados.

Para abordar esta questão, o ITeamStateProvider foi introduzido de modo a facultar aos fornecedores de modelos acesso às alterações de estado que poderão afectar as decorações da equipa. Para além disso, as vistas de modelos podem utilizar um SynchronizationStateTester para determinar quando as etiquetas dos elementos de modelos necessitam de ser actualizadas. Esta API depende da interface ITeamStateProvider para determinar quando o estado da equipa de um recurso foi alterada e pode ser transmitida para o decorador da equipa como sendo parte de um IDecorationContext.