Foswiki::Store::VC::Handler

internal package Foswiki::Store::VC::Handler

This class is PACKAGE PRIVATE to Store::VC, and should never be used from anywhere else. It is the base class of implementations of individual file handler objects used with stores that manipulate files stored in a version control system (phew!).

The general contract of the methods on this class and its subclasses calls for errors to be signalled by Error::Simple exceptions.

There are a number of references to RCS below; however this class is useful as a base class for handlers for all kinds of version control systems which use files on disk.

For readers who are familiar with Foswiki version 1.0.0, this class is analagous to Foswiki::Store::RcsFile.

ClassMethod new($store, $web, $topic, $attachment)

Constructor. There is one object per stored file.

$store is the Foswiki::VC::Store object that contains the cache for objects of this type. A cache is used because at some point we'll be smarter about the number of calls to RCS code we make.

Note that $web, $topic and $attachment must be untainted!

ObjectMethod finish()

Break circular references.

ObjectMethod getInfo($version) → \%info

• $version if 0 or undef, or out of range (version number > number of revs) will return info about the latest revision.

Returns info where version is the number of the rev for which the info was recovered, date is the date of that rev (epoch s), user is the canonical user ID of the user who saved that rev, and comment is the comment associated with the rev.

Designed to be overridden by subclasses, which can call up to this method if simple file-based rev info is required.

ObjectMethod addRevisionFromText($text, $comment, $cUID, $date)

Add new revision. Replace file with text.

• $text of new revision
• $comment checkin comment
• $cUID is a cUID.
• $date in epoch seconds; may be ignored

ObjectMethod addRevisionFromStream($fh, $comment, $cUID, $date)

Add new revision. Replace file with contents of stream.

• $fh filehandle for contents of new revision
• $cUID is a cUID.
• $date in epoch seconds; may be ignored

ObjectMethod replaceRevision($text, $comment, $cUID, $date)

Replace the top revision.

• $text is the new revision
• $date is in epoch seconds.
• $cUID is a cUID.
• $comment is a string

ObjectMethod getRevisionHistory() → $iterator

Get an iterator over the identifiers of revisions. Returns the most recent revision first.

The default is to return an iterator from the current version number down to 1. Return rev 1 if the file exists without history. Return an empty iterator if the file does not exist.

ObjectMethod getLatestRevisionID() → $id

Get the ID of the most recent revision. This may return undef if there have been no revisions committed to the store.

ObjectMethod getNextRevisionID() → $id

Get the ID of the next (as yet uncreated) revision. The handler is required to implement this because the store has to be able to embed the revision ID into TOPICINFO before the revision is actually created.

If the file exists without revisions, then rev 1 does exist, so next rev should be rev 2, not rev 1, so the first change with missing history doesn't get merged into rev 1.

ObjectMethod getLatestRevisionTime() → $text

Get the time of the most recent revision

ObjectMethod getTopicNames() → @topics

Get list of all topics in a web

• $web - Web name, required, e.g. 'Sandbox'

Return a topic list, e.g. ( 'WebChanges',  'WebHome', 'WebIndex', 'WebNotify' )

ObjectMethod revisionExists($rev) → $boolean

Determine if the identified revision actually exists in the object history.

ObjectMethod getWebNames() → @webs

Gets a list of names of subwebs in the current web

ObjectMethod moveWeb( $newWeb )

Move a web.

ObjectMethod getRevision($version) → ($text, $isLatest)

• $version if 0 or undef, or out of range (version number > number of revs) will return the latest revision.

Get the text of the given revision, and a flag indicating if this is the most recent revision.

Designed to be overridden by subclasses, which can call up to this method if the main file revision is required.

ObjectMethod storedDataExists() → $boolean

Establishes if there is stored data associated with this handler.

ObjectMethod restoreLatestRevision( $cUID )

Restore the plaintext file from the revision at the head.

ObjectMethod remove()

Destroy, utterly. Remove the data and attachments in the web.

Use with great care! No backup is taken!

ObjectMethod moveTopic( $store, $newWeb, $newTopic )

Move/rename a topic.

ObjectMethod copyTopic( $store, $newWeb, $newTopic )

Copy a topic.

ObjectMethod moveAttachment( $store, $newWeb, $newTopic, $newAttachment )

Move an attachment from one topic to another. The name is retained.

ObjectMethod copyAttachment( $store, $newWeb, $newTopic, $newAttachment )

Copy an attachment from one topic to another. The name is retained unless $newAttachment is defined.

ObjectMethod isAsciiDefault ( ) → $boolean

Check if this file type is known to be an ascii type file.

ObjectMethod setLock($lock, $cUID)

Set a lock on the topic, if $lock, otherwise clear it. $cUID is a cUID.

SMELL: there is a tremendous amount of potential for race conditions using this locking approach.

It would be nice to use flock to do this, but the API is unreliable (doesn't work on all platforms)

ObjectMethod isLocked( ) → ($cUID, $time)

See if a lock exists. Return the lock user and lock time if it does.

ObjectMethod setLease( $lease )

• $lease reference to lease hash, or undef if the existing lease is to be cleared.

Set an lease on the topic.

ObjectMethod getLease() → $lease

Get the current lease on the topic.

ObjectMethod removeSpuriousLeases( $web )

Remove leases that are not related to a topic. These can get left behind in some store implementations when a topic is created, but never saved.

ObjectMethod openStream($mode, %opts) → $fh

Opens a file handle onto the store. This method is primarily to support virtual file systems.

$mode can be '<', '>' or '>>' for read, write, and append respectively. %

%opts can take different settings depending on $mode.

• $mode='<'
  • version - revision of the object to open e.g. version => 6 Default behaviour is to return the latest revision. Note that it is much more efficient to pass undef than to pass the number of the latest revision.
• $mode='>' or ='>>'
  • no options

ObjectMethod synchroniseAttachmentsList(\@old) → @new

Synchronise the attachment list from meta-data with what's actually stored in the DB. Returns an ARRAY of FILEATTACHMENTs. These can be put in the new tom.

This function is only called when the {RCS}{AutoAttachPubFiles} configuration option is set.

ObjectMethod getAttachmentList() → @list

Get list of attachment names actually stored for topic.

ObjectMethod stringify()

Generate string representation for debugging

ObjectMethod recordChange($cUID, $rev, $more)

Record that the file changed, and who changed it

ObjectMethod eachChange($since) → $iterator

Return iterator over changes - see Store for details

ObjectMethod numRevisions() → $integer

Must be provided by subclasses that do not implement:

• revisionExists

Find out how many revisions there are. If there is a problem, such as a nonexistent file, returns 0.

Must not be called outside this class and subclasses.

ObjectMethod initBinary()

Must be provided by subclasses that do not implement

• init

Initialise a binary file.

ObjectMethod initText()

Must be provided by subclasses that do not implement

• init

Initialise a text file.

ObjectMethod deleteRevision()

Delete the last revision - do nothing if there is only one revision

Virtual method - must be implemented by subclasses

ObjectMethod revisionDiff ( $rev1, $rev2, $contextLines ) → \@diffArray

rev2 newer than rev1. Return reference to an array of [ diffType, $right, $left ]

Virtual method - must be implemented by subclasses

ObjectMethod getRevision($version) → $text

Get the text for a given revision. The version number must be an integer.

Virtual method - must be implemented by subclasses

ObjectMethod getRevisionAtTime($time) → $rev

Get a single-digit version number for the rev that was alive at the given epoch-secs time, or undef it none could be found.

Virtual method - must be implemented by subclasses