Helix SwarmHelix Swarm

Source.html

  • //
  • guest/
  • perforce_software/
  • revml/
  • product/
  • release/
  • 0.90/
  • html/
  • VCP/
  • Source.html #1
  • View
  • Commits
  • Open Download .zip Download (10 KB) 
  1. <html><head><title>VCP::Source - A base class for repository sources</title></head><body><h1><a name="NAME">NAME
  2.  
  3. </a></h1><p>VCP::Source - A base class for repository sources
  4.  
  5. <p><hr><h1><a name="SYNOPSIS">SYNOPSIS
  6.  
  7. </a></h1><p><hr><h1><a name="DESCRIPTION">DESCRIPTION
  8.  
  9. </a></h1><p><hr><h1><a name="OPTIONS">OPTIONS
  10.  
  11. </a></h1><dl><dt><a name="_bootstrap_"><strong><p>--bootstrap
  12.  
  13. </strong></a><pre>  --bootstrap=pattern
  14.  
  15. </pre><dd>Forces all files matching the given shell regular expression (may use
  16. wildcards like &quot;*&quot;, &quot;?&quot;, and &quot;...&quot;) to have their first revisions
  17. transferred as complete copies instead of deltas.  This is useful when
  18. you want to transfer a revision other than the first revision as the
  19. first revision in the target repository.  It is also useful when you
  20. want to skip some revisions in the target repository (although the <a href="VCP/Filter/map.html">Map
  21. filter</a> has superceded this use).
  22.  
  23. <dt><a name="_continue_"><strong><p>--continue
  24.  
  25. </strong></a><dd>Tells VCP to continue where it left off from last time.  This will not
  26. detect new branches of already transferred revisions (this limitation
  27. should be lifted, but results in an expensive rescan of metadata), but
  28. will detect updates to already transferred revisions.
  29.  
  30. </dl><p><hr><h1><a name="SUBCLASSING">SUBCLASSING
  31.  
  32. </a></h1><p>This class uses the fields pragma, so you'll need to use base and 
  33. possibly fields in any subclasses.  See <a>VCP::Plugin</a> for methods
  34. often needed in subclasses.
  35.  
  36. <h2><a name="Subclass_utility_API">Subclass utility API
  37.  
  38. </a></h2><dl><dt><a name="options_spec_"><strong><p>options_spec
  39.  
  40. </strong></a><dd>Adds common VCP::Source options to whatever options VCP::Plugin parses:
  41.  
  42. <dt><a name="dest_"><strong><p>dest
  43.  
  44. </strong></a><dd>Sets/Gets a reference to the VCP::Dest object.  The source uses this to
  45. call handle_header(), handle_rev(), and handle_end() methods.
  46.  
  47. <dt><a name="continue_"><strong><p>continue
  48.  
  49. </strong></a><dd>Sets/Gets the CONTINUE field (which the user sets via the --continue flag)
  50.  
  51. <dt><a name="real_source_"><strong><p>real_source
  52.  
  53. </strong></a><dd>Returns the reference to be used when sending revisions to the destination.
  54.  
  55. <p>Each revision has a pointer to the source that sends it so that filters
  56. and destinations can call get_source_file().
  57.  
  58. <p>Most sources return $self; Sources that spool data, such as
  59. VCP::Source::metadb, need to specify a real source.  They do so by
  60. overloading this method.  VCP::Source::revml does not do this, as it
  61. supplies a get_source_file().
  62.  
  63. <dt><a name="rev_mode_"><strong><p>rev_mode
  64.  
  65. </strong></a><pre>    my $mode = $self-&gt;rev_mode( $filebranch_id, $rev_id );
  66.  
  67. </pre><dd>Returns FALSE, &quot;base&quot;, or &quot;normal&quot; as a function of the filebranch and
  68. rev_id.  Do not queue the revision if this returns FALSE (you may also
  69. skip any preceding revisions).  Queue it only as a base revision if it
  70. returns &quot;base&quot;, and queue it as a full revision otherwise.
  71.  
  72. <p>Not all base revs will be sent; base revs that have no child revs will
  73. not be sent.
  74.  
  75. <p>Always returns &quot;normal&quot; when not in continue mode.
  76.  
  77. <dt><a name="queue_rev_"><strong><p>queue_rev
  78.  
  79. </strong></a><dd>Some revs can't be sent immediately.  They get queued.  Once queued, the
  80. revision may not be altered.  All revisions must be queued before being
  81. sent.  All revs from the source repository should be queued, --continue
  82. processing is automatic.  Placeholders should be inserted for all branches,
  83. even empty ones.
  84.  
  85. <p>This updates last_rev and last_rev_for_filebranch.
  86.  
  87. <p>Returns FALSE if the rev cannot be queued, for instance if it's already
  88. been queued once.
  89.  
  90. <p>rev_mode() should be called before creating a rev, or at least before
  91. queue_rev()ing it in order to see if and in what form the rev should be
  92. sent.
  93.  
  94. <dt><a name="queued_rev_"><strong><p>queued_rev
  95.  
  96. </strong></a><pre>    $self-&gt;queued_rev( $id );
  97.  
  98. </pre><dd>Returns a queued rev by id.
  99.  
  100. <p>Sources where revs can arrive willy-nilly, like VCP::Source::revml, queue
  101. up all revs and need to randomly access them.
  102.  
  103. <dt><a name="last_rev_"><strong><p>last_rev
  104.  
  105. </strong></a><dd>Returns the last revision queued.
  106.  
  107. <dt><a name="last_rev_for_filebranch_"><strong><p>last_rev_for_filebranch
  108.  
  109. </strong></a><pre>    $self-&gt;last_rev_for_filebranch( $filebranch_id );
  110.  
  111. </pre><dd>Returns the last revision queued on the indicated filebranch.
  112.  
  113. <dt><a name="set_last_rev_in_filebranch_previous_id_"><strong><p>set_last_rev_in_filebranch_previous_id
  114.  
  115. </strong></a><pre>    $self-&gt;set_last_rev_in_filebranch_previous_id( $r );
  116.  
  117. </pre><dd>If there is a last_rev_for_filebranch for $r-&gt;filebranch_id, sets its
  118. previous_id to point to $r.  This is useful for sources which scan
  119. in most-recent-first order.
  120.  
  121. <dt><a name="already_queued_"><strong><p>already_queued
  122.  
  123. </strong></a><pre>    $self-&gt;already_queued( $id );
  124.  
  125. </pre><dd>Returns true if the indicated id was queued.
  126.  
  127. <dt><a name="queued_rev_count_"><strong><p>queued_rev_count
  128.  
  129. </strong></a><dd>Returns (does not set) the number of revs queued so far.
  130.  
  131. <p>Replaces the deprecated function sent_rev_count().
  132.  
  133. <dt><a name="store_cached_revs_"><strong><p>store_cached_revs
  134.  
  135. </strong></a><pre>    $self-&gt;store_cached_revs;
  136.  
  137. </pre><dd>For parsers which read history one file at a time and branch in rev_id
  138. space, like VCP::Source::cvs, it's possible to flush all revs to disk
  139. after each file is parsed.  This method takes the last VCP::Rev in
  140. each filebranch and stores it to disk, freeing memory.
  141.  
  142. <dt><a name="send_revs_"><strong><p>send_revs
  143.  
  144. </strong></a><pre>    $self-&gt;send_revs;
  145.  
  146. </pre><dd>Removes and sends all revs accumulated so far.  Called automatically
  147. after scan_metadata().
  148.  
  149. </dl><p><hr><h1><a name="SUBCLASS_OVERLOADS">SUBCLASS OVERLOADS
  150.  
  151. </a></h1><p>These methods should be overridded in any subclasses.
  152.  
  153. <dl><dt><a name="scan_metadata_"><strong><p>scan_metadata
  154.  
  155. </strong></a><dd>This is called to scan the metadata for the source repository.  It
  156. should call rev_mode() for each revision found (including any that need
  157. to be concocted to make up for collapsed metadata in the source, like
  158. VSS or CVS deletes or CVS branch creation) and if that returns TRUE,
  159. then queue_rev() should be called.
  160.  
  161. <p>If rev_mode() returns &quot;base&quot;, then the transfer is in --continue mode
  162. and this rev should be built as or converted to a base revision.  The
  163. easiest way to do this is to build it normally and then call
  164. $r-&gt;base_revify().
  165.  
  166. <p>If the metadata source returns metadata from most recent to oldest, as
  167. do most file history reports, the previous_id() need not be set until
  168. the next revision in a filebranch is scanned.  The most recent rev
  169. passed to queue_rev() is available by calling last_rev(), if the
  170. metadata is one branch at a time, and the last rev in each filebranch is
  171. available by calling last_rev_for_filebranch().
  172.  
  173. <p>If the metadata is scanned one file or filebranch at a time and
  174. branched are all created by the time the end of a file's metadata
  175. arrives, calling store_cached_revs() will flush all queued revs from the
  176. last_rev() and last_rev_for_filebranch() in-memory caches to the disk
  177. cache (all other revs are flushed as their successors arrive).
  178.  
  179. <p>There is no easy way to handle randomly ordered metadata at this time,
  180. typically a source will accumulate as little as it can in memory and
  181. queue the rest.  See VCP::Source::cvs for an example of this.
  182.  
  183. <p>Once scan_metadata() is complete, send_revs() will be called
  184. automatically.
  185.  
  186. <dt><a name="get_source_file_"><strong><p>get_source_file
  187.  
  188. </strong></a><dd>All sources must provide a way for the destination to fetch a revision.
  189.  
  190. <dt><a name="handle_header_"><strong><p>handle_header
  191.  
  192. </strong></a><dd>REQUIRED OVERLOAD.
  193.  
  194. <p>Subclasses must add all repository-specific info to the $header, at least
  195. including rep_type and rep_desc.
  196.  
  197. <pre>   $header-&gt;{rep_type} =&gt; 'p4',
  198.    $self-&gt;p4( ['info'], \$header-&gt;{rep_desc} ) ;
  199.  
  200. </pre><p>The subclass must pass the $header on to the dest:
  201.  
  202. <pre>   $self-&gt;dest-&gt;handle_header( $header )
  203.       if $self-&gt;dest;
  204.  
  205. </pre><p>This may be called when dest is null to allow the source to initialize
  206. itself when it won't be scanning the real source.  So the if $self-&gt;dest
  207. is important.
  208.  
  209. <p>That's not the case for copy_revs().
  210.  
  211. <dt><a name="handle_footer_"><strong><p>handle_footer
  212.  
  213. </strong></a><dd>Not a required overload, as the footer carries no useful information at
  214. this time.  Overriding methods must call this method to pass the
  215. $footer on:
  216.  
  217. <pre>   $self-&gt;SUPER::handle_footer( $footer ) ;
  218.  
  219. </pre><dt><a name="parse_time_"><strong><p>parse_time
  220.  
  221. </strong></a><pre>   $time = $self-&gt;parse_time( $timestr ) ;
  222.  
  223. </pre><dd>Parses &quot;[cc]YY/MM/DD[ HH[:MM[:SS]]]&quot;.
  224.  
  225. <p>Will add ability to use format strings in future.
  226. HH, MM, and SS are assumed to be 0 if not present.
  227.  
  228. <p>Returns a time suitable for feeding to localtime or gmtime.
  229.  
  230. <p>Assumes local system time, so no good for parsing times in revml, but that's
  231. not a common thing to need to do, so it's in VCP::Source::revml.pm.
  232.  
  233. <dt><a name="bootstrap_"><strong><p>bootstrap
  234.  
  235. </strong></a><dd>Sets (and parses) or gets the bootstrap spec.
  236.  
  237. <p>Can be called plain:
  238.  
  239. <pre>   $self-&gt;bootstrap( $bootstrap_spec ) ;
  240.  
  241. </pre><p>See the command line documentation for the format of $bootstrap_spec.
  242.  
  243. <dt><a name="is_bootstrap_mode_"><strong><p>is_bootstrap_mode
  244.  
  245. </strong></a><pre>   ... if $self-&gt;is_bootstrap_mode( $file ) ;
  246.  
  247. </pre><dd>Compares the filename passed in against the list of bootstrap regular
  248. expressions set by <a href="#bootstrap">/bootstrap</a>.
  249.  
  250. <p>The file should be in a format similar to the command line spec for
  251. whatever repository is passed in, and not relative to rev_root, so
  252. &quot;//depot/foo/bar&quot; for p4, or &quot;module/foo/bar&quot; for cvs.
  253.  
  254. <p>This is typically called in the subbase class only after looking at the
  255. revision number to see if it is a first revision (in which case the
  256. subclass should automatically put it in bootstrap mode).
  257.  
  258. </dl><p><hr><h1><a name="COPYRIGHT">COPYRIGHT
  259.  
  260. </a></h1><p>Copyright 2000, Perforce Software, Inc.  All Rights Reserved.
  261.  
  262. <p>This module and the VCP package are licensed according to the terms given in
  263. the file LICENSE accompanying this distribution, a copy of which is included in
  264. <a href="vcp.html">vcp</a>.
  265.  
  266. <p><hr><h1><a name="AUTHOR">AUTHOR
  267.  
  268. </a></h1><p>Barrie Slaymaker &lt;barries@slaysys.com&gt;
  269.  
  270. <p><hr><i><font size="-1">Last updated: Thu Jul 15 01:02:44 2004</font></i></body></html>
# Change User Description Committed
#1 4344 alan_teague Revised productization files updating to latest perl modules and
normalizing scripts to w...ork on both linux and bsd platforms. «		 21 years ago