Difference between revisions of "Corona HowTo: Integrate a Repository"

Revision as of 12:09, 21 December 2006

Repository Integration Steps

Overview Repository Integration

1. Identify Repository you want to integrate. The term Repository is used generically to describe a set of related resources with interfaces to retrieve and update the resources it holds. A repository may be an DBMS table, XML file, CVS, etc.
   1. We refer the content items in a repository as repository resources or just resources.
2. Find the repository interfaces for retrieving and updating resources
3. Correlate these interfaces to the interfaces defined by IRepository
4. IRepositoryAdapter extends IRepository (at least it should-bug)
5. Define a repository-descriptor specifying the information needed to connect to your repository as repository-connection-parameter(s)
6. Add repository-descriptor definition into your context-container definition
7. If needed extend the IRepository interface for your repository
8. Implement IRepositoryAdapter methods in the repository adapter, extend this if you extended IRepository interface
9. Add an extension to the RepositoryAdapter extension point in org.eclipse.corona.repository called org.eclipse.corona.repository.adapter. Take a look at org.eclipse.corona.repository.RepositoryAdapterFactory to see how the extensions are processed.

Extending IRepository

If you need some special methods for your repository you should extend IRepository and IRepositoryAdapter. IRepository needs to be a separate interface in case you want to utilize the Corona SOA support for your repository. You may not want to expose all of the same methods on your Web Service interface to your repository on a server as you expose on the IRepositoryAdapter on the client.

RepositoryDescriptors

A ContextContainer can hold many repository-descriptor(s). A repository-descriptor holds information to establish a connection to a repository. Here is an example of a specialized ContextContainer called a project-context-container The repository-descriptor is described by the following schema fragment:

	<xs:complexType name="repository-descriptor">
		<xs:sequence>
			<xs:element name="description" type="xs:string"/>
			<xs:element maxOccurs="1" minOccurs="0" name="repository-configurations" type="con:repository-configurations"/>
		</xs:sequence>
		<xs:attribute name="name" type="xs:string" use="required"/>
		<xs:attribute name="uri" type="xs:anyURI" use="required"/>
		<xs:attribute name="content-type" type="xs:anyURI" use="required"/>
	</xs:complexType>
	
	<xs:complexType name="repository-configurations">
		<xs:sequence>
			<xs:element maxOccurs="unbounded" minOccurs="0" name="repository-configuration" type="con:repository-configuration"/>
		</xs:sequence>
        	<xs:attribute name="default-configuration-name" type="xs:string" use="required"/>
	</xs:complexType>

    <xs:complexType name="repository-configuration">
		<xs:sequence>
				<xs:element maxOccurs="unbounded" minOccurs="0" name="repository-connection-parameters" type="con:repository-connection-parameters"/>
		</xs:sequence>
        <xs:attribute name="name" type="xs:string" use="required"/>
    </xs:complexType>

     <xs:complexType name="repository-connection-parameters">
		<xs:sequence>
			<xs:element maxOccurs="unbounded" minOccurs="0" name="repository-connection-parameter" type="con:repository-connection-parameter"/>
			<!-- only one resource-subset allowed per one connection parameters set -->
			<xs:element maxOccurs="1" minOccurs="0" name="resource-subset" type="con:resource-subset"/>
		</xs:sequence>
		<xs:attribute name="name" type="xs:string"/>
		<xs:attribute name="access-type" type="xs:anyURI" use="required"/>
    </xs:complexType>

    <xs:complexType name="repository-connection-parameter">
		 <xs:attribute name="name" type="xs:string" use="required"/>
         <xs:attribute name="value" type="xs:string" use="required"/>
    </xs:complexType>

    <xs:complexType name="resource-subset">
		<xs:attribute name="type" type="xs:anyURI" use="required"/>
		<xs:attribute name="selection-criteria" type="xs:string" use="required"/>
     </xs:complexType>

This schema serves as an input for SDO model code generator.

Main objects used with a Repository

• RepositoryDescriptor
  • the object that describes how to find and connect to a repository
• RepositoryDescriptorViewer
  • the object that knows how to display RepositoryDescriptor information
  • currently the closest thing to an implementation is the default EMF Editor for RepositoryDescriptor org.eclipse.corona.model.container.edit.RepositoryDescriptorItemProvider
• IRepository
  • the basic interfaces required by Corona Framework for handling repositories
• ISpecificRepository - you extend the IRepository interface to add methods specific to your repository needed beyond those defined in IRepository.
• RepositoryImplementation
  • the repository you want to make available to the Corona Framework
  • normally you already have an implementation of this object and you just what to integrate it into the Corona Framework
• IRepositoryAdaptor - defines method specific to integrating a repository to the Corona Framework
• RepositoryAdaptorImplementation
  • your implementation of an adapter for a specific repository
  • this object that connects to and interacts with the RepositoryImplementation
  • it exposes the IRepositoryAdapter interface so your repository can work in the Corona Framework
• RepositoryAdapterViewer - NOT IMPLEMENTED the object that knows how to display repository adaptor information
• RepositoryViewer - the object that knows how to display some or all of the resources within a repository

Why do I need IRepository and IRepositoryAdapter Interfaces?

• IRepository is specific to the repository
• IRepositoryAdapter may include other "house keeping" functions required for integration with Corona Framework
• You may want to expose your IRepository implementation as web service and not expose the Corona "house keeping" methods in your web service.

I need an example

• Look in org.eclipse.corona.repository
  • for interface definitions
• Look at org.eclipse.corona.repository.adapter.team
  • for an example of extending IRepository to ITeamRepository and an implementation of TeamRepositoryAdapter
• Look at org.eclipse.corona.repository.xml.team
  • this is just a XML file loaded into a DOM it just shows how you can have a stand-alone "repository" wrapped with TeamRepositoryAdapter to integrate into the Corona Framework.

How a RepositoryAdapter gets packaged

1. A plugin holding a Repository Integration should contain the following -
   1. A RepositoryAdaptor and RepositoryAdaptorFactory Extension implementation
   2. A RepositoryDescriptor constants class to hold the reposition-connection-parameter names.
   3. Specific viewers/editors may be installed - see HowTo: Add a new page to Project Container View
   4. specially written viewers may not be required if Eclipse already has a viewer available i.e. html browser
   5. A manifest.mf exporting the RepositoryAdapter and RepositoryAdaptorFactory
   6. A plugin.xml definition for the extension points for editors and viewers
   7. A plugin.xml definition for the editor and viewer extensions
2. Typically we expect a client api to an existing repository to be available and to be wrapped as a plugin that the RepositoryAdapter can use. However, you may be able to establish a remote connection to the repository through the RepositoryAdapter an work with the repository directly.

How a RepositoryAdapter gets deployed

1. install the RepositoryAdapter Plugin to <eclipse home>/eclipse/plugins

RepositoryDescriptor

• the class implementation is found in org.eclipse.corona.model.container.Repository package
• holds basic information used to locate a respository of information for example URI, authentication properties, connection properties
• holds properties regarding access to the repository
• API
• updateRepositoryConfiguration(RepositoryName, RepositoryConfigurationName, RepositoryConfiguration) - add/remove/change properties defined in the RepositoryDescriptor (repository-configuration)
• How a Repository Descriptor gets created
  • Pick the target RepositoryDescriptor type from a list.
  • MatchMaker provides appropriate RepositoryDescriptorEditorViewer.
  • The MatchMaker will retrieve the RepositoryDescriptorEditorViewer's job to create descriptor from factory and populate.

RepositoryDescriptorEditorViewer - no implementation available

• Need user interface for defining a new RepositoryDescriptor - after Demo

RepositoryDescriptorFactory - current implementation is the ProjectContainerManager

• makes RepositoryDescriptors and deals with singleton-type relationships
• How a RepositoryDescriptor gets Saved/Read
  • It's the RepositoryDescriptorFactory's job to deal with saving and reading of RepositoryDescriptors into Containers. Containers should be reference by uri, which must enforce uniqueness.

RepositoryAdaptor - currently the closest thing is the org.eclipse.corona.server.container.common.IRepository

• object that interacts with the actual repository
• consumes a RepositoryDescriptor and optionally connects to the target Repository.
• It is the sole responsibility of the adaptor to mediate between the repository and any consumer of repository information. If the repository is accessed via webservices/jdbc/rmi, it's the adaptor's issue.
• It is the adaptor's job to expose the repository contents as an object model.
• API
  • open - uses connection properties and authentication properties from the RepositoryDescriptor to connect to the respository. Should there be a reopen when a reconnection to a repository is needed?
  • close - closes the connection to a repository
  • resourceExists - verify whether a resource exists in the repository
  • addResource - add a resource to the repository
  • removeResource - remove a resource to the repository
  • fetchResource - retrieve a resource from the repository
  • fetchNativeRepositoryClient - (we don't have an implementation of this) return the object that provides native client access to the particular repository. This allows custom views which are capable of using the native repository interface to do so
  • getRepositoryCapabilities - returns indicator of the capabilities that a repository supports. Review WSDM Capability specification.

RepositoryAdaptorFactory

• makes RepositoryAdaptors
  • IRepositoryAdapter repositoryAdapter = repositoryAdapterFactory.createRepositoryAdaptor(repositoryDescriptor);
  • createRepositoryAdapter method matches the repository-descriptor passed to it based upon the content-type

to a registered

Repository

• How a Repository gets connected
  • The xxx gets RepositoryAdapter is activated
  • RepositoryDescriptor repositoryDescriptor = projectContainer.getRepositoryDescriptor(TEAM_MEMBER_REPOSITORY_NAME);
  • RepositoryAdapterFactory repositoryAdapterFactory = new RepositoryAdapterFactory();
  • IRepositoryAdapter repositoryAdapter = repositoryAdapterFactory.createRepositoryAdaptor(repositoryDescriptor);
    • The createRepositoryAdaptor
  • repositoryAdapter.open();

• • Given a RepositoryDescriptor, the MatchMaker finds an appropriate RepositoryAdaptorFactory, and requests that factory to provide an RepositoryAdaptor using the target RepositoryDescriptor. The Matchmaker tracks the RepositoryDescriptor/RepositoryAdaptor pair.

Repository Example Implementation

• TeamRepository - currently org.eclipse.corona.server.repository.team.TeamRepository
  • Assumption: Team members could have different roles in different project contexts. So, I think each project would have a reference to it own TeamRepository.
  • API
    • addMember(MemberName)
    • removeMember(MemberName)
    • setMemberRole(MemberName, RoleName) - the role name should be well defined and each role name be unique, I'm thinking OWL/RDF defintion of Roles.
    • getMemberRole - return the primary role defined in this Repository
    • getMemberRoles(MemberName) - return list of all roles on a project
    • deleteMember(MemberName) - remove the member from this repository
    • setMemberPrimaryRole(MemberName, Role) - not currently needed
    • setMemberProperties(MemberName, Properties) - not currently needed

RepositoryAdaptor Implementation - still needed

• ArtifactRepository - should implement/extend RepositoryAdaptor
  • holds properties regarding access to artifacts probably just a wrapper around CVS, Subversion etc.
  • see ALF vocabulary definitions for Source Code Management (SCM).
  • I think we only want to be able to retrieve a specifically versioned artifact.
  • Do we need to update a versioned artifact or can we just receive notification of the update?

How to test a RepositoryAdapter

1. Future
   1. We plan to implement a MatchMaker class that matches Viewers to Repository resources. The idea is that the MatchMaker will choose the highest fidelity viewer available for a particular Repository Resource. It will probably be based upon mime types and some type of extension for items without defined mime types.
   2. It should be used as logic for RepositoryAdapterFactory's createRepositoryAdaptor to match repository
2. MatchMaker - a utility for matching and tracking combinations of the other objects...see below
   1. RepositoryAdaptorFactory registers with MatchMaker
   2. RepositoryDescriptorFactory registers with MatchMaker
   3. The bundle activator should register the factories with the MatchMaker.
   4. The new RepositoryDescriptorFactory type will be surfaced later in the GUI (pick-list, etc.). Some provision may need to be made for an icon...

NOTE: The viewers and editors are typically extension points. Adaptors should be implemented as services.

Nice to have

• ProcessCollaborationRepository
  • holds properties regard access to process defintion, hopefully the API on the Eclipse Process Framework (EPF Project) will be rich enough that can access Process information.
  • will have to monitor EPF API's to see how this will work

Nice to have

• TaskCollaborationRepository
  • RepositoryAdaptor or an actual implementation if shared Task repository needed by Mylar
  • API
    • addTask
    • removeTask
    • setTaskProperties

RepositoryViewer

• currently a ProjectContainerRepositoryPage ????
• consumes an adaptor/configuration pair and interacts with the repository via the RepositoryAdaptor interface (and whatever extended interfaces the adaptor makes available
• How a Repository gets Viewed
  • Given a RepositoryAdaptor, the MatchMaker returns a list of RepositoryViewers (sorted most to least preferred).
  • The RepositoryDescriptor information corresponding to the RepositoryAdaptor is retrievable from the tracked descriptor/ adaptor pair (see previous comments)

MatchMaker

• currently no implementation or interface
• matches adaptors to descriptors, viewers to descriptors, and viewers to adaptors.
• the MatchMaker is responsible for knowing how to match a descriptor with adaptor and viewers, tracking combination pairs, and matching viewers with adaptors based on their bound state.
• It's the MatchMaker's job to identify the appropriate viewer/editor. This is done by computing the best

match based on the descriptor's generic parameters (see sample xml comments).

• The MatchMaker returns a list of viewers (sorted most to least preferred).

Resources

The ProjectContainer does not contain project resources. The ProjectContainer holds references to repositories, resources and artifacts. The ProjectContainer will use URI based references whenever possible. The URI identification approach meshes with the Corona SOA orientation as well as the Knowledge Base OWL/RDF object metadata defintion.

Collaboration Events

Collaboration Events will notify the Project Container of project change activities occurring on Eclipse Client. The ProjectContainer will if needed forward Collaboration Events from one Eclipse Client to another.

Repository Event Focus

The ContextContainer acts as lense to focus all events related to a resources used within the container. This focus create a central knowledge collection point for the Corona Knowledge Base. You can create your own event listener to monitor events.