Important information for authors of TWiki user mappers

The published APIs of some user-mapper related classes have changed between 4.2.0 and 4.2.1. This document is provided as documentation of those changes aimed specifically at authors of user mappers.

As a general point the POD documentation of the classes involved in user mapping has been extended and clarified. Authors of user mappers should review the documentation in case they have made any assumptions that are not supported by the clarified documenation. A typical example is the passing of anything but a cUID to the methods of TWiki::Users.

TWiki::Users

forceCUID has been removed. This method was responsible for mapping login names, cUIDs and wiki names to cUIDs, and was expected to be idempotent over the set of cUIDs. There were signifcant issues with the mapping performed by this method and it has had to be removed.

A new method, mapLogin2cUID, replaces one of the functions of forceCUID, the mapping of a login name to a cUID. This is a static function designed to be called from custom user mappers that support a one-to-one login-to-cUID mapping. When forceCUID saw a character outside the range [a-zA-Z0-9_], it would map individual bytes to a zero-padded decimal. This has changed in mapLogin2cUID such that the individual bytes of a character outside the range [a-zA-Z0-9] will be mapped to two-digit hex number preceded by an underscore. This apparently minor change means that the mapLogin2cUID mapping is now reversible (the original login name can be recovered from a cUID encoded using mapLogin2cUID). However more importantly it also means that the mapping is no longer idempotent over the set of cUIDs, which is the fundamental change triggering most of the others described here.

The most important change in this module is that getCanonicalUserID no longer accepts a cUID as parameter. This has a knock-on effect on the other methods of the class that used it to process their parameters. Specifically, the following methods no longer accept a login name or wiki name. This does not change the documented behaviour of the functions, but does change the actual behaviour.

• setEmails (now requires a cUID or a group name)
• isAdmin
• isInList
• getLoginName
• getWikiName
• webDotWikiName
• isInGroup (first parameter)
• setPassword
• removeUser

Mapper base class changes

There are two base classes typically used for deriving new mappers, TWiki::UserMapping and TWiki::Users::TWikiUserMapping. Both of these classes have changed. Since TWiki::Users::TWikiUserMapping is a subclass of TWiki::UserMapping, changes to the base class also affect it.

TWiki::UserMapping

getCanonicalUserID has been renamed to login2cUID. This renaming is to separate the function from TWiki::Users::getCanonicalUserID (which accepts different parameters, and has a much more generic function) and to reveal the true intention of the function. The parameters are unchanged. Mappers that redefine this function must define login2cUID instead, bearing in mind the narrower specification.

Note: To support older user mappers, getCanonicalUserID will still be called if (and only if) login2cUID is not defined.

The default generic implementation of isInGroup has been moved from TWikiUserMapping and is now available for other mappers to use. However it is very inefficient and should generally be avoided.

TWiki::Users::TWikiUserMapping

Because this mapping relied on the removed method forceCUID to perform the mapping from login names to cUIDs, subclassers of this class should be aware that cUID encodings have changed. That means that cUIDs generated using this mapping that have been stored into topics cannot be mapped into "new style" cUIDs, and the user information encoded therein is lost.

TWiki::Func

The changes to TWiki::Users have had the knock-on effect of tightening up the implementation of the functions that are used to get information about users. None of the documented specifications have changed, but the implementations are now intolerant of being passed inappropriate parameter types (login names and wiki names) in the same way as the methods of TWiki::Users, described above.

-- Contributors: CrawfordCurrie - 28 Jul 2008

Discussion

Good overview.

For info - 4.2.1 is set to be released 03 Aug 2008.

In case severe issues are found bý authors of those contribs that uses this API and the related functions - we will collect those in a 4.2.2 release - probably in September.

The alternative is to delay 4.2.1 again by at least a month and there are more than 120 good reasons not to do that.

-- KennethLavrsen - 28 Jul 2008