| RE: [stellation-res] Initial Eclipse client APIs posted for discussion |
> >-----Original Message----- > >From: stellation-res-admin@xxxxxxxxxxxxxxx > >[mailto:stellation-res-admin@xxxxxxxxxxxxxxx]On Behalf Of Jim Wright - > >IBM Research > >Sent: October 4, 2002 12:48 PM > >To: stellation-res@xxxxxxxxxxxxxxx > >Subject: [stellation-res] Initial Eclipse client APIs posted for > >discussion > > > > > >I've just checked in some preliminary Stellation CM APIs > >(model-level Stellation APIs for Eclipse). > >This is very much a work in progress (even more so than the > >rest of Stellation!) and feedback would be very helpful. > > > >The goals of the new API include: > >* providing a more Eclipse-friendly interface for Stellation, > > using Eclipse platform APIs wherever sensible. > >* supporting simple, direct interaction with Stellation > > repositories and branch images (the current kludge > > requires indirect access through portions of > > the Stellation svc command-line client). > >* providing groundwork for future use of fine-grained aggregates > >* preventing ongoing changes in workspace code from > > rippling the Eclipse client code. > >* improving performance (the current kludge requires firing > > up a new JVM and opening/closing a Stellation svc > > workspace every time a high-level Stellation service > > is requested. > > > >** Where Is It? > > > >This new API is being developed using a separate package > >within the org.eclipse.stellation.scm.model plug-in. In other > >words - I'm not creating yet another plug-in, but transforming > >an existing one. > > > >Interfaces and classes for the new API are located in > >Eclipse plug-in project org.eclipse.stellation,scm.model, > >in package org.eclipse.stellation.scm.model2. > >The CVS path is > >plugins/org.eclipse.stellation.scm.model/src/org.eclipse.stellati > >on.scm.model2 > > > >(The original ....scm.model package still contains the classes > >used for talking to the command-line svc workspace code, to > >avoid breaking the current Eclipse client). > > > >There is also a new top-level 'doc' folder for this plug-in > >project, (same > >level as the 'src' folder. It contains Overview and Issues docs, a > >ChangeLog for the 'model2' work, and other docs to come. > > > >** What's In It? > > > >The current checkin includes five interfaces and one class: > > > > IScmProject > > IScmFactory > > IScmAccessPoint > > IScmArtifactMap > > IScmConfiguration > > ScmAccessSpec > > ScmException > > > >IScmProject represents a Stellation project associated with a particular > >Eclipse project (IProject). It includes: > >- methods for getting project-level information (e.g. current > > branch/version, configuration, status....) > >- methods for requesting Stellation services (e.g. checkin, > >checkout, fork, > > clean, merge) > >- methods for updating the current project image when Eclipse resources > > change (e.g. add, move, remove) > >You can also access the associated BranchImage for > >Artifact-level operations > >(needed for future fine-grained > >support), as well as the project's ArtifactMap and Configuration. > > > >------------------- > > > >IScmFactory is a singleton interface for creating new > >IScmProjects, opening > >existing ones, creating repository AccessPoints and other > >top-level Scm operations as needed. When implemented, it will > >be accessed > >through ScmModelPlugin.getFactory . > > > >------------------- > > > >IScmAccessPoint supports coordinated use of several ...stellation.repos > >interfaces and classes: AccessPoint, Handle and Authenticator. > >ScmAccessPoints are created from an ScmAccessSpec, which packages all > >details needed for a particular user to access a particular > >repository. (An > >earlier version of ScmAccessSpecs is used in the current > >...scm.model code). > > > >Design goals for IScmAccessPoint include: > >- relatively long lifetime (up to session lifetime) > >- ability to close and reopen the underlying Handle, if needed > >for network > >or database performance reasons > >- ability to share a single AccessPoint across multiple concurrent > >ScmProjects using the same repository > >- direct access to the underlying stellation.repo objects for > >most services > > (after opening the ScmAccessPoint, call getHandle() and use Handle > > methods as before). > > > >There is a 1:N relationship between ScmAccessPoints and ScmProjects > > > >------------------- > > > >IScmArtifactMap handles mapping between Artifacts and the > >corresponding Eclipse resources. It also handles the mechanics > >of updating the current project image when Eclipse project resources > >change. In future, I plan to extend it to provide resource-level status > >information (e.g. unmanaged/new/modified/stale) in a form usable > >by Eclipse GUI widgets such as Decorators. > > > >In the current design, IScmArtifactMap contains a nested class, Entry, > >wrapping the tuple <ArtifactID,Artifact,IPath,Attributes,StatusFlags>. > >All internal maps (e.g. id-to-artifact, path-to-artifact, id-to-path, > >id-to-artifactStatus, etc. etc.) point to a shared Entry; goals > >here include better guarantees for data consistency, improved > >performance (e.g. for multiple mappings related to a single Artifact), > >and easier maintenance. > > > >There is a 1:1 relationship between ScmArtifactMaps and ScmProjects. > > > >------------------- > > > >IScmConfiguration contains three type of configuration information: > >- general Stellation options, > >- suffix-based file-to-artifact-type mapping > >- pattern-based file-to-artifact-type mapping > > > >This interface is largely based on the workspace.Configuration class. > >However, it's not yet clear if it's a good match for "the way Eclipse > >does things". This will be re-evaluated as implementation proceeds. > > > >There is a 1:1 relationship between ScmConfigurations and ScmProjects. > > > >------------------- > > > >ScmException is the standard exception thrown by all IScm interfaces. > >It's derived from the Eclipse-standard CoreException, and is used for > >smoother integration with Eclipse error handling facilities. One can > >easily attach one or more lower-level exceptions (e.g > >StellationException, > >RepositoryException) to an ScmException, which should avoid > >losing information when such exceptions are converted to ScmExceptions. > >-- Your documents prompted me to make a start at a document that I feel is missing from Stellation, namely an overall architecture document that describes the various Stellation components and how they fit together. So I have made a first attempt at putting such a document together, and in the process I have identified a possible architecture for Stellation that is sufficiently decoupled so as to be easy to maintain in the future as requirements change. Even if you find the specific suggestions that I have made to be unacceptable, I think that the idea of the document is important and that the team should jointly flesh out the content based on whatever overall architecture is agreed on. The document is in HTML format, but I have not had a chance to verify it with a variety of browsers and have not had any chance to look at it under Linux. However I have verified that it is displayable using Mozilla 1.1. Regards Jonathan Personal Email jgossage@xxxxxxxx Business Email jonathan@xxxxxxxxxxxxxx
Attachment:
arch.tar
Description: Unix tar archive