data/TWiki/TWikiUserMappingDotPm.txt
author Colas Nahaboo <colas@nahaboo.net>
Sat, 26 Jan 2008 15:50:53 +0100
changeset 0 414e01d06fd5
child 1 e2915a7cbdfa
permissions -rw-r--r--
RELEASE 4.2.0 freetown
colas@0
     1
---+ Package =TWiki::UserMapping=
colas@0
     2
colas@0
     3
This is a virtual base class (a.k.a an interface) for all user mappers. It is
colas@0
     4
*not* useable as a mapping in TWiki - use the BaseUserMapping for default
colas@0
     5
behaviour.
colas@0
     6
colas@0
     7
User mapping is the process by which TWiki maps from a username (a login name)
colas@0
     8
to a display name and back. It is also where groups are maintained.
colas@0
     9
colas@0
    10
See TWiki::Users::BaseUserMapping and TWiki::Users::TWikiUserMapping for
colas@0
    11
the default implementations of this interface.
colas@0
    12
colas@0
    13
If you want to write a user mapper, you will need to implement the methods
colas@0
    14
described in this class.
colas@0
    15
colas@0
    16
User mappings work by mapping both login names and display names to a
colas@0
    17
_canonical user id_. This user id is composed from a prefix that defines
colas@0
    18
the mapper in use (something like 'BaseUserMapping_' or 'LdapUserMapping_')
colas@0
    19
and a unique user id that the mapper uses to identify the user.
colas@0
    20
colas@0
    21
The null prefix is reserver for the TWikiUserMapping for compatibility
colas@0
    22
with old TWiki releases.
colas@0
    23
colas@0
    24
__Note:__ in all the following documentation, =$user= refers to a
colas@0
    25
*canonical user id*.
colas@0
    26
colas@0
    27
colas@0
    28
%TOC%
colas@0
    29
colas@0
    30
---++ PROTECTED ClassMethod new ($session, $mapping_id)
colas@0
    31
colas@0
    32
Construct a user mapping object, using the given mapping id.
colas@0
    33
colas@0
    34
colas@0
    35
---++ ObjectMethod *finish* <tt>()</tt>
colas@0
    36
Break circular references.
colas@0
    37
colas@0
    38
colas@0
    39
colas@0
    40
---++ ObjectMethod *loginTemplateName* <tt>() -> $templateFile</tt>
colas@0
    41
colas@0
    42
Allows UserMappings to come with customised login screens - that should
colas@0
    43
preferably only over-ride the UI function
colas@0
    44
colas@0
    45
Default is "login"
colas@0
    46
colas@0
    47
colas@0
    48
colas@0
    49
---++ ObjectMethod *supportsRegistration* <tt>() -> $boolean</tt>
colas@0
    50
colas@0
    51
Return true if the UserMapper supports registration (ie can create new users)
colas@0
    52
colas@0
    53
Default is *false*
colas@0
    54
colas@0
    55
colas@0
    56
colas@0
    57
---++ ObjectMethod *handlesUser* <tt>($cUID,$login,$wikiname) -> $boolean</tt>
colas@0
    58
colas@0
    59
Called by the TWiki::Users object to determine which loaded mapping
colas@0
    60
to use for a given user (must be fast).
colas@0
    61
colas@0
    62
Default is *false*
colas@0
    63
colas@0
    64
colas@0
    65
colas@0
    66
---++ ObjectMethod *getCanonicalUserID* <tt>($login,$dontcheck) -> cUID</tt>
colas@0
    67
colas@0
    68
Convert a login name to the corresponding canonical user name. The
colas@0
    69
canonical name can be any string of 7-bit alphanumeric and underscore
colas@0
    70
characters, and must correspond 1:1 to the login name.
colas@0
    71
(undef on failure)
colas@0
    72
colas@0
    73
(if dontcheck is true, return a cUID for a nonexistant user too - used for registration)
colas@0
    74
colas@0
    75
Subclasses *must* implement this method.
colas@0
    76
colas@0
    77
colas@0
    78
colas@0
    79
colas@0
    80
---++ ObjectMethod *getLoginName* <tt>($cUID) -> login</tt>
colas@0
    81
colas@0
    82
Converts an internal cUID to that user's login
colas@0
    83
(undef on failure)
colas@0
    84
colas@0
    85
Subclasses *must* implement this method.
colas@0
    86
colas@0
    87
colas@0
    88
colas@0
    89
---++ ObjectMethod *addUser* <tt>($login,$wikiname,$password,$emails) -> cUID</tt>
colas@0
    90
colas@0
    91
Add a user to the persistant mapping that maps from usernames to wikinames
colas@0
    92
and vice-versa, via a *canonical user id* (cUID).
colas@0
    93
colas@0
    94
$login and $wikiname must be acceptable to $TWiki::cfg{NameFilter}.
colas@0
    95
$login must *always* be specified. $wikiname may be undef, in which case
colas@0
    96
the user mapper should make one up.
colas@0
    97
colas@0
    98
This function must return a canonical user id that it uses to uniquely
colas@0
    99
identify the user. This can be the login name, or the wikiname if they
colas@0
   100
are all guaranteed unigue, or some other string consisting only of 7-bit
colas@0
   101
alphanumerics and underscores.
colas@0
   102
colas@0
   103
If you fail to create a new user (for eg your Mapper has read only access),
colas@0
   104
<pre>
colas@0
   105
    throw Error::Simple('Failed to add user: '.$error);
colas@0
   106
</pre>
colas@0
   107
where $error is a descriptive string.
colas@0
   108
colas@0
   109
Throws an Error::Simple if user adding is not supported (the default).
colas@0
   110
colas@0
   111
colas@0
   112
colas@0
   113
---++ ObjectMethod *removeUser* <tt>($user) -> $boolean</tt>
colas@0
   114
colas@0
   115
Delete the users entry from this mapper. Throws an Error::Simple if
colas@0
   116
user removal is not supported (the default).
colas@0
   117
colas@0
   118
colas@0
   119
colas@0
   120
---++ ObjectMethod *getWikiName* <tt>($cUID) -> wikiname</tt>
colas@0
   121
colas@0
   122
Map a canonical user name to a wikiname.
colas@0
   123
colas@0
   124
Returns the $cUID by default.
colas@0
   125
colas@0
   126
colas@0
   127
colas@0
   128
---++ ObjectMethod *userExists* <tt>($cUID) -> $boolean</tt>
colas@0
   129
colas@0
   130
Determine if the user already exists or not. Whether a user exists
colas@0
   131
or not is determined by the password manager.
colas@0
   132
colas@0
   133
Subclasses *must* implement this method.
colas@0
   134
colas@0
   135
colas@0
   136
colas@0
   137
---++ ObjectMethod *eachUser* <tt>() -> listIteratorofcUIDs</tt>
colas@0
   138
colas@0
   139
Called from TWiki::Users. See the documentation of the corresponding
colas@0
   140
method in that module for details.
colas@0
   141
colas@0
   142
Subclasses *must* implement this method.
colas@0
   143
colas@0
   144
colas@0
   145
colas@0
   146
---++ ObjectMethod *eachGroupMember* <tt>($group) -> TWiki::ListIteratorofcUIDs</tt>
colas@0
   147
colas@0
   148
Called from TWiki::Users. See the documentation of the corresponding
colas@0
   149
method in that module for details.
colas@0
   150
colas@0
   151
Subclasses *must* implement this method.
colas@0
   152
colas@0
   153
colas@0
   154
colas@0
   155
---++ ObjectMethod *isGroup* <tt>($user) -> boolean</tt>
colas@0
   156
colas@0
   157
Called from TWiki::Users. See the documentation of the corresponding
colas@0
   158
method in that module for details.
colas@0
   159
colas@0
   160
Subclasses *must* implement this method.
colas@0
   161
colas@0
   162
colas@0
   163
colas@0
   164
---++ ObjectMethod *eachGroup* <tt>() -> ListIteratorofgroupnames</tt>
colas@0
   165
colas@0
   166
Called from TWiki::Users. See the documentation of the corresponding
colas@0
   167
method in that module for details.
colas@0
   168
colas@0
   169
Subclasses *must* implement this method.
colas@0
   170
colas@0
   171
colas@0
   172
colas@0
   173
---++ ObjectMethod *eachMembership* <tt>($cUID) -> ListIteratorofgroupsthisuserisin</tt>
colas@0
   174
colas@0
   175
Called from TWiki::Users. See the documentation of the corresponding
colas@0
   176
method in that module for details.
colas@0
   177
colas@0
   178
Subclasses *must* implement this method.
colas@0
   179
colas@0
   180
colas@0
   181
colas@0
   182
---++ ObjectMethod *isAdmin* <tt>($user) -> $boolean</tt>
colas@0
   183
colas@0
   184
True if the user is an administrator. Default is *false*
colas@0
   185
colas@0
   186
colas@0
   187
colas@0
   188
---++ ObjectMethod *isInGroup* <tt>($user,$group,$scanning) -> bool</tt>
colas@0
   189
colas@0
   190
Called from TWiki::Users. See the documentation of the corresponding
colas@0
   191
method in that module for details.
colas@0
   192
colas@0
   193
Default is *false*
colas@0
   194
colas@0
   195
colas@0
   196
colas@0
   197
---++ ObjectMethod *findUserByEmail* <tt>($email) -> \@users</tt>
colas@0
   198
   * =$email= - email address to look up
colas@0
   199
Return a list of canonical user names for the users that have this email
colas@0
   200
registered with the password manager or the user mapping manager.
colas@0
   201
colas@0
   202
Returns an empty list by default.
colas@0
   203
colas@0
   204
colas@0
   205
colas@0
   206
---++ ObjectMethod *getEmails* <tt>($user) -> @emailAddress</tt>
colas@0
   207
colas@0
   208
If this is a user, return their email addresses. If it is a group,
colas@0
   209
return the addresses of everyone in the group.
colas@0
   210
colas@0
   211
Duplicates should be removed from the list.
colas@0
   212
colas@0
   213
By default, returns the empty list.
colas@0
   214
colas@0
   215
colas@0
   216
colas@0
   217
---++ ObjectMethod *setEmails* <tt>($user,@emails)</tt>
colas@0
   218
colas@0
   219
Set the email address(es) for the given user. Does nothing by default.
colas@0
   220
colas@0
   221
colas@0
   222
colas@0
   223
---++ ObjectMethod *findUserByWikiName* <tt>($wikiname) -> listofcUIDsassociatedwiththatwikiname</tt>
colas@0
   224
colas@0
   225
Called from TWiki::Users. See the documentation of the corresponding
colas@0
   226
method in that module for details.
colas@0
   227
colas@0
   228
Subclasses *must* implement this method.
colas@0
   229
colas@0
   230
colas@0
   231
colas@0
   232
---++ ObjectMethod *checkPassword* <tt>($userName,$passwordU) -> $boolean</tt>
colas@0
   233
colas@0
   234
Finds if the password is valid for the given user.
colas@0
   235
colas@0
   236
Returns 1 on success, undef on failure.
colas@0
   237
colas@0
   238
Default behaviour is to return 1.
colas@0
   239
colas@0
   240
colas@0
   241
colas@0
   242
---++ ObjectMethod *setPassword* <tt>($user,$newPassU,$oldPassU) -> $boolean</tt>
colas@0
   243
colas@0
   244
If the $oldPassU matches matches the user's password, then it will
colas@0
   245
replace it with $newPassU.
colas@0
   246
colas@0
   247
If $oldPassU is not correct and not 1, will return 0.
colas@0
   248
colas@0
   249
If $oldPassU is 1, will force the change irrespective of
colas@0
   250
the existing password, adding the user if necessary.
colas@0
   251
colas@0
   252
Otherwise returns 1 on success, undef on failure.
colas@0
   253
colas@0
   254
Default behaviour is to fail.
colas@0
   255
colas@0
   256
colas@0
   257
colas@0
   258
---++ ObjectMethod *passwordError* <tt>() -> $string</tt>
colas@0
   259
colas@0
   260
Returns a string indicating the error that happened in the password handlers
colas@0
   261
TODO: these delayed errors should be replaced with Exceptions.
colas@0
   262
colas@0
   263
returns undef if no error 9the default)
colas@0
   264
colas@0
   265
colas@0
   266
colas@0
   267
---++ ObjectMethod *ASSERT_IS_CANONICAL_USER_ID* <tt>($user_id) -> $boolean</tt>
colas@0
   268
colas@0
   269
Used for debugging to ensure we are actually passing a canonical_id
colas@0
   270
colas@0
   271
colas@0
   272
colas@0
   273
---++ ObjectMethod *ASSERT_IS_USER_LOGIN_ID* <tt>($user_login) -> $boolean</tt>
colas@0
   274
colas@0
   275
Used for debugging to ensure we are actually passing a user login
colas@0
   276
colas@0
   277
colas@0
   278
colas@0
   279
---++ ObjectMethod *ASSERT_IS_USER_DISPLAY_NAME* <tt>($user_display) -> $boolean</tt>
colas@0
   280
colas@0
   281
Used for debugging to ensure we are actually passing a user display_name
colas@0
   282
(commonly a WikiWord Name)
colas@0
   283
colas@0
   284
Returns true by default.
colas@0
   285
colas@0
   286