The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
SVN-Friendly-0.999_002
River stage zero No dependents
++
/ SVN::Friendly::Repos

NAME

SVN::Friendly::Repos - user friendly Subversion API for the repository management

SYNOPSIS

  use SVN::Friendly::Repos;

  #--------------------------------------------------
  # Create a repository
  #--------------------------------------------------

  $oRepos = create($sRootPath, $xConfig, $xConfigFs, $oUuid);

  #--------------------------------------------------
  # Get access to an existing repository
  #--------------------------------------------------

  $oRepos = SVN::Friendly::Repos->new($sRootPath);

  #--------------------------------------------------
  # About the repository
  #--------------------------------------------------
  #
  # $iHook    - may be any of the following constants
  #
  #             $oRepos->PRE_COMMIT
  #             $oRepos->START_COMMIT
  #             $oRepos->PRE_REVPROP
  #             $oRepos->POST_REVPROP
  #             $oRepos->PRE_OBLITERATE
  #             $oRepos->POST_OBLITERATE
  #             $oRepos->PRE_LOCK
  #             $oRepos->POST_LOCK
  #             $oRepos->PRE_UNLOCK
  #             $oRepos->POST_UNLOCK
  #
  # $iAprTime   microseconds since the epoch (Jan 1,1970,00:00:00 UTC)



  $oRepos->getUUID();

  $oRepos->getRoot();

  $oRepos->getFormat();

  $oRepos->getFileSystemType();

  $oRepos->getHead();

  $oRepos->getYoungestRevision($iAprTime);



  $oRepos->getHookDir();

  $oRepos->getHookFile($iHook);

  $oRepos->getDbDir();

  $oRepos->getLockDir();

  $oRepos->getDbLogLockFile();

  $oRepos->getConfDir();

  $oRepos->getSvnserverConfFile();

  #--------------------------------------------------
  # Configuration management
  #--------------------------------------------------

  $oRepos->setUUID($sUUID);
  $oRepos->setUUID($sUUID, $oPool);

  $oRepos->enableRevProps();
  $oRepos->enableRevProps($sScript);


  #--------------------------------------------------
  # Get the svn_repos_t object
  #--------------------------------------------------

  $oSvnRepos = $oRepos->getSvnRepos();

DESCRIPTION

The class provides user friendly access to API routines needed for configuring and retrieving information from the repository.

What is a repository?

A subversion repository stores the canonical or "official" copies of a set of documents as well as all the steps needed to reconstruct past official versions.

This cannonical set can be replicated on multiple machines or locations provided that all copies share the same UUID. The repository can also be moved. Working copies that checked out documents from the old location will still be able to access the new location provided the old and new locations have the same UUID.

The repository can be viewed as a composite of several different subsystems:

* a filesystem or database that stores the documents and all of their history. You can choose the particular implementation you want for the filesystem.

* an authorization system for determining who may make changes or extract data from the repository.

* a runtime system that monitors activity and injects custom functionality via hook scripts.

* a server management system that determines what protocols may be used to access the repository and configures them.

Methods not yet defined for this object

At present there is only a skeletal implementation of the class. If you need to use additional methods, for now, you will have to explore the unadorned Subversion SWIG bindings. You will also need to pass those methods a svn_repos_t object. This can be retrieved via the getSvnRpos() method.

For a list of C-API functions, see http://svn.collab.net/svn-doxygen/svn__repos_8h.html

The usual rules for converting the C-API to Perl bindings apply:

* callback + baton parameters are collapsed into a single callback parameter

* "OUT" parameters are returned as return values. if there are multiple such parameters the Perl function will return a list. The list members will be in the same order as the return values.

* the trailing pool parameter is optional. All other parameters must at least be represented by an actual parameter. Some methods allow undef as a parameter; others require that an actual value be provided.

For further discussion see SVN::Friendly::Client.

USAGE

Creating a repository from scratch

  # $sRootPath  - local file system path to the root of the
  #               repository
  #
  # $xConfig    - a SVN::Friendly::Config object, or a hash
  #               or directory path name suitable for creating
  #               one - see SVN::Friendly::Config
  #
  # $xConfigFs  - hash storing option-value pairs describing
  #               the type of file system that will be used
  #               to build the repository.  Keys are option
  #               names, values are option values. See below
  #               See below for details.
  #
  # $oUuid      - the respositories Uuid. This should be left
  #               undefined except when creating a repository
  #               that is meant to be a mirror of an existing
  #               repository.

  $oRepos = create($sRootPath, $xConfig, $xConfigFs, $oUuid);

Opening an existing repository

  $oRepos = SVN::Friendly::Repos->new($sRootPath);
  $oRepos = SVN::Friendly::Repos->new($oSvnRepos);
  $oRepos = SVN::Friendly::Repos->new($oRepos);

The new will reopen an existing repository or create an object wrapper around an already opened respository. You can pass it the local root of the reposiory, a SVN::Friendly::Repos object or a svn_repos_t object and it will "do the right thing". If a wrapper has already been created, it will use that, otherwise it will create a fresh one.

(Note: the list of already crated wrappers is stored using weak references so there is no need to worry that repository objects will stay live in memory forever.).

Configuration management

There is a great deal that can be done to expand this classes capabilities for programmatic repository management. At present there are just two methods:

  $oRepos->setUUID($sUUID);
  $oRepos->setUUID($sUUID, $oPool);

  $oRepos->enableRevProps();
  $oRepos->enableRevProps($sScript);
setUUID

Sets the repository UUID after it has been created. This method should be used with extreme care, and only on a repository that is a meant to be a mirror or backup for the original repository assigned to $sUUID.

Additionally, if there is any chance that there are outstanding working copies, the owners of those working copies should commit all changes. Once a UUID has changed on a repository, any working copies checked out with the old UUID will no longer be able to post to that repository. They will only be able to post to repositories that have the old UUID.

enableRevProps

Revision properties cannot be edited unless the repository has installed a PRE_REVPROP hook script that exits with 0. If called without parameters, this method installs a skeletal version of such a script. If called with the $sScript it installs the content of $sScript in the revision property hook file.

VERSION COMPATIBILITY

See SVN::Friendly.

CAVEATS

None to date.

KNOWN BUGS

None to date.

TO DO/ROADMAP

See SVN::Friendly

VOLUNTEERS

If anyone would like to be involved in testing or expanding the user friendly interface, please contact the maintainer.

Feedback on the documentation, bugs, usability, or additional features desired is welcome. Time and person-power permitting the most commonly requested features will be implemented.

SEE ALSO

See SVN::Friendly

AUTHOR

Elizabeth Grace Frank-Backman

COPYRIGHT

Copyright (c) 2008-2011 Elizabeth Grace Frank-Backman. All rights reserved.

LICENSE

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.