Skip to main content
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index] [List Home]
[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.stellation.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.
--
Jim Wright, IBM T.J. Watson Research Center
*** The Stellation project: Advanced SCM for Collaboration
*** http://www.eclipse.org/stellation
*** Work Email: jwright@xxxxxxxxxxxxxx ------- Personal Email: jim.wright@xxxxxxx

Back to the top