ScottVenier and KenSchalk were talking about the possibility of adding a class to ReposUI to represent a package. This would provide some higher-level operations than VestaSource and wouldm make it easier to write applications like VestaWeb (e.g. a GUI). This page contians some notes on how we could do this.

Classes

We probably need several classes:

Things that we don't need more classes for:

Base class

We probably want a base class for all of these. Maybe this should be VDirSurrogate, or maybe it should be a new class.

VersionContainer class

Abstract base class (should never actually be instantiated). It's concrete sub-classes are Package, Branch, and Session.

Member functions:

Other notes:

Session class

Derived from VersionContainer and adds these additional member functions:

Package class

Derived from VersionContainer and adds these additional member functions:

Branch class

Derived from Package. Does it add anything?

We think we'll keep this because branches may become more interesting in the future. (See vupdateandbranches.)

Version class

WorkingDir class

Member functions:

Reservation class

Member functions:

Related Functions

There should be a function to give a canonical sorted order of the versions and version reservations within a package/branch/session (VersionContainer) and it's contents(?). This should include any ghosted versions as well with some indication that they are ghosts.

What about methods to perform checkout, checkin etc.?

We've talked before about the idea of turning the command-line tools (vcheckout, vcheckin, vbranch, etc.) into call-able API functions. However, this not at all a simple task for several reasons:

We do believe that having an API for performing the operations is desirable, but because of these complications we don't think it should be a requirement for the first version of the interface which this page is about. Simply providing information about the revision control objects in a meaningful way with common code is a good first step.

Other notes

Development Plan

Not important for the initial version:

Tricky Issues

Use iterator classes for looping over multiple objects (Package::versions, Version::ancestors, etc.). We think this will work reasonable well across SWIG. These should be lazy iterators (not doing any work until they have to.)

Use type identification functions on base class to handle functions that return one of N different types.

Existing Implementations

ReposUIPackage Implementation and Concerns

Current version of ReposUIPackage: repos_ui/36.ReposUIPackage/3. It also uses repos/62.ReposUIPackage/1 and basics/os/21.common_parent/1

Classes hierarchy

Some implementation concerns that were brought up previously and theirs current solutions

BranchesEnum* Package::branches()
VersionsEnum* VersionContainer::versions()
SessionsEnum* Package::sessions()
ReservationsEnum* Package::reservations()
GhostsEnum* VersionContainer::ghosts()

AncestorsEnum* VersionContainer::ancestors(Text hints = "")
AncestorsEnum* Version::ancestors(Text hints = "")

NextBranchesEnum* Version::nextBranches()
NextVersionsEnum* Version::nextVersions()
NextSessionsEnum* Version::nextSessions()

// hasWorkDir: returns true if work-dir attribute is set, false otherwise
// (case vcheckout -W)
bool hasWorkDirAttrib() throw (SRPC::failure)

// workingDir: returns WorkingDir object if it's an active session, and 
// NULL if session is not active or work-dir attribute is not set. 
// if go_to_master is false it looks for working directory in the same 
// repository, if go_to_master is true it looks for the working directory 
// in other repositories. 
WorkingDir* workingDir(bool go_to_master = false)
      throw (ReposUI::failure, VestaConfig::failure, SRPC::failure);

   // hasWorkDir: returns true if work-dir attribute is set, false otherwise
    // (case vcheckout -W)
    bool hasWorkDirAttrib() throw (SRPC::failure)
    { return isAttribSet("work-dir"); }
    
    // workingDir: returns WorkingDir object if it's an active session, and 
    // NULL if session is not active or work-dir attribute is not set. 
    // If go_to_master is false the work dir is only looked up in local 
    // repository. if go_to_master is true then master copy of the 
    // session is looked up and working dir is looked up in the repository 
    // where session's master copy was found.   
    WorkingDir* workingDir(bool go_to_master = false)
      throw (ReposUI::failure, VestaConfig::failure, SRPC::failure);

SWIG concerns