001/*
002 * file CqUser.java
003 *
004 * Licensed Materials - Property of IBM
005 * Restricted Materials of IBM 
006 *
007 * com.ibm.rational.wvcm.stp.cq.CqUser
008 *
009 * (C) Copyright IBM Corporation 2006, 2014.  All Rights Reserved.
010 * Note to U.S. Government Users Restricted Rights:  Use, duplication or 
011 * disclosure restricted by GSA ADP  Schedule Contract with IBM Corp.
012 */
013
014package com.ibm.rational.wvcm.stp.cq;
015
016import static com.ibm.rational.wvcm.stpex.StpExBase.PROPERTY_NAMESPACE;
017
018import java.util.List;
019
020import javax.wvcm.Feedback;
021import javax.wvcm.ResourceList;
022import javax.wvcm.WvcmException;
023import javax.wvcm.PropertyNameList.PropertyName;
024
025import com.ibm.rational.wvcm.stp.StpPartialResultsException;
026import com.ibm.rational.wvcm.stp.StpProperty;
027import com.ibm.rational.wvcm.stp.StpResource;
028import com.ibm.rational.wvcm.stpex.StpExEnumeration;
029import com.ibm.rational.wvcm.stpex.StpExEnumerationBase;
030
031/**
032 * The proxy interface for information stored in a DbSet for a single user. A
033 * users login, access privileges and some other information can be retrieved
034 * and specified through this object. You can also subscribe and unsubscribe a
035 * user to databases and upgrade user information in all the user databases that
036 * the user is currently subscribed to.
037 * <p>
038 * Note that CqUser.doWriteProperties(...) writes dirty properties of this proxy
039 * into the DbSet. For the new values to be visible to a user database,
040 * {@link CqUserDb#doUpgradeUsersAndGroups(Feedback)} must be invoked on that
041 * database or {@link CqUser#doUpgradeDatabases(Feedback)} must be invoked on
042 * this user.
043 * <p>
044 * The user-friendly specification for the location of a user has the form
045 * 
046 * <pre>
047 *  <b>cq.user:</b><i>&lt;user-name&gt;</i>@<i>&lt;db-set&gt;</i>
048 * </pre>
049 */
050public interface CqUser extends CqResource, CqUserInfo
051{
052    /** The database set that contains this user resource */
053    PropertyName<CqDbSet> DB_SET =
054        new PropertyName<CqDbSet>(PROPERTY_NAMESPACE, "db-set");
055
056    /**
057     * Returns the value of the {@link #DB_SET DB_SET} property as defined by
058     * this proxy.
059     * 
060     * @return A CqDbSet proxy for the database set that contains this resource.
061     * 
062     * @throws WvcmException if this proxy does not define a value for the
063     *             {@link #DB_SET DB_SET} property.
064     */
065    CqDbSet getDbSet() throws WvcmException;
066
067    /**
068     * An enumeration of the authentication modes available to a user
069     */
070    enum AuthenticationMode implements StpExEnumeration
071    {
072        /** LDAP authentication is being used by this user */
073        LDAP,
074
075        /** Traditional ClearQuest authentication is being used by this user */
076        CLEAR_QUEST
077    }
078
079    /**
080     * Whether this user is authenticated via an LDAP login or via ClearQuest
081     * login-name and password.
082     */
083    static PropertyName<AuthenticationMode> AUTHENTICATION_MODE =
084        new PropertyName<AuthenticationMode>(PROPERTY_NAMESPACE,
085                                             "authentication-mode");
086
087    /**
088     * Returns the value of the {@link #AUTHENTICATION_MODE AUTHENTICATION_MODE}
089     * property as defined by this proxy.
090     * 
091     * @return An AuthenticationMode enumerator indicating what method is used
092     *         to authenticate this user. Will never be <b>null</b>.
093     * 
094     * @throws WvcmException if this proxy does not define a value for the
095     *             {@link #AUTHENTICATION_MODE AUTHENTICATION_MODE} property.
096     */
097    AuthenticationMode getAuthenticationMode() throws WvcmException;
098
099    /**
100     * Defines a new value for the
101     * {@link #AUTHENTICATION_MODE AUTHENTICATION_MODE} property of this proxy.
102     * <p>
103     * When setting the authentication mode to CLEAR_QUEST authentication, the
104     * AUTHENTICATOR property specifies the new ClearQuest password.
105     * <p>
106     * When setting the authentication mode to LDAP authentication, the
107     * AUTHENTICATOR property specifies the LDAP login name (a ClearQuest
108     * password is not used for LDAP authentication).
109     * 
110     * @param mode An AuthenticationMode enumerator specifying the new
111     *            authentication mode for this user.
112     * 
113     * @see #setLoginName(String)
114     * @see #setAuthenticator(String)
115     */
116    void setAuthenticationMode(AuthenticationMode mode);
117
118    /**
119     * The user's e-mail address.
120     */
121    static PropertyName<String> EMAIL =
122        new PropertyName<String>(PROPERTY_NAMESPACE, "email");
123
124    /**
125     * Returns the value of the {@link #EMAIL EMAIL} property as defined by this
126     * proxy.
127     * 
128     * @return A String containing the email field of this user's profile. Will
129     *         never be <b>null</b>.
130     * 
131     * @throws WvcmException if this proxy does not define a value for the
132     *             {@link #EMAIL EMAIL} property.
133     */
134    String getEmail() throws WvcmException;
135
136    /**
137     * Defines a new value for the {@link #EMAIL EMAIL} property of this proxy.
138     * 
139     * @param email A String containing the new value for the email field of
140     *            this user's profile
141     */
142    void setEmail(String email);
143
144    /**
145     * The full name of the user
146     */
147    static PropertyName<String> FULL_NAME =
148        new PropertyName<String>(PROPERTY_NAMESPACE, "full-name");
149
150    /**
151     * Returns the value of the {@link #FULL_NAME FULL_NAME} property as defined
152     * by this proxy.
153     * 
154     * @return A String containing the full name field of this user's profile.
155     *         Will never be <b>null</b>.
156     * 
157     * @throws WvcmException if this proxy does not define a value for the
158     *             {@link #FULL_NAME FULL_NAME} property.
159     */
160    String getFullName() throws WvcmException;
161
162    /**
163     * Defines a new value for the {@link #FULL_NAME FULL_NAME} property of this
164     * proxy.
165     * 
166     * @param fullName A String containing the new value for the full name field
167     *            of this user's profile
168     */
169    void setFullName(String fullName) throws WvcmException;
170
171    /**
172     * A list of active user groups to which the user belongs.
173     * 
174     * The list can be empty.
175     */
176    static PropertyName<ResourceList<CqGroup>> GROUPS =
177        new PropertyName<ResourceList<CqGroup>>(PROPERTY_NAMESPACE, "groups");
178
179    /**
180     * Returns the value of the {@link #GROUPS GROUPS} property as defined by
181     * this proxy.
182     * 
183     * @return A ResourceList containing a CqGroup proxy for each group this
184     *         user belongs to. Will never be <b>null</b>.
185     * 
186     * @throws WvcmException if this proxy does not define a value for the
187     *             {@link #GROUPS GROUPS} property.
188     */
189    ResourceList<CqGroup> getGroups() throws WvcmException;
190
191    /**
192     * The miscellaneous information field of the user's profile.
193     */
194    static PropertyName<String> MISCELLANEOUS_INFORMATION =
195        new PropertyName<String>(PROPERTY_NAMESPACE,
196                                 "miscellaneous-information");
197
198    /**
199     * Returns the value of the
200     * {@link #MISCELLANEOUS_INFORMATION MISCELLANEOUS_INFORMATION} property as
201     * defined by this proxy.
202     * 
203     * @return A String containing the content of the miscellaneous information
204     *         field of this user's profile. Will never be <b>null</b>.
205     * 
206     * @throws WvcmException if this proxy does not define a value for the
207     *             {@link #MISCELLANEOUS_INFORMATION MISCELLANEOUS_INFORMATION}
208     *             property.
209     */
210    String getMiscellaneousInformation() throws WvcmException;
211
212    /**
213     * Defines a new value for the
214     * {@link #MISCELLANEOUS_INFORMATION MISCELLANEOUS_INFORMATION} property of
215     * this proxy.
216     * 
217     * @param miscInfo A String containing the new value for the miscellaneous
218     *            information field of this user's profile
219     */
220    void setMiscellaneousInformation(String miscInfo);
221
222    /**
223     * The string used by ClearQuest to identify this user. Note: if LDAP
224     * authentication is enabled for this user, the value of this property may
225     * not actually be used for login, as the name of the property might
226     * suggest.
227     */
228    static PropertyName<String> LOGIN_NAME =
229        new PropertyName<String>(PROPERTY_NAMESPACE, "login-name");
230
231    /**
232     * Returns the value of the {@link #LOGIN_NAME LOGIN_NAME} property as
233     * defined by this proxy.
234     * 
235     * @return A String containing the login name field of the user's profile.
236     *         Will never be <b>null</b>.
237     * 
238     * @throws WvcmException if this proxy does not define a value for the
239     *             {@link #LOGIN_NAME LOGIN_NAME} property.
240     */
241    String getLoginName() throws WvcmException;
242
243    /**
244     * Defines a new value for the {@link #LOGIN_NAME LOGIN_NAME} property of
245     * this proxy. Note, changing the login name of a user changes the location
246     * of the CqUser object for that user.
247     * 
248     * @param loginName A String containing the new value for the login-name
249     *            field of this user's profile
250     */
251    void setLoginName(String loginName);
252
253    /**
254     * An encrypted version of the value placed in the AUTHENTICATOR property of
255     * this CqUser resource.
256     */
257    static PropertyName<String> AUTHENTICATOR =
258        new PropertyName<String>(PROPERTY_NAMESPACE, "authenticator");
259
260    /**
261     * Returns the value of the {@link #AUTHENTICATOR AUTHENTICATOR} property as
262     * defined by this proxy.
263     * 
264     * @return A String containing an encrypted copy of the value of the
265     *         AUTHENTICATOR property of this user resource. Will never be
266     *         <b>null</b>.
267     * 
268     * @throws WvcmException if this proxy does not define a value for the
269     *             {@link #AUTHENTICATOR AUTHENTICATOR} property.
270     */
271    String getAuthenticator() throws WvcmException;
272
273    /**
274     * Defines a new value for the {@link #AUTHENTICATOR AUTHENTICATOR} property
275     * of this proxy. In LDAP AUTHENTICATION_MODE, or when changing to LDAP
276     * AUTHENTICATION_MODE, this property specifies the LDAP login name to be
277     * associated with this ClearQuest user. In CLEAR_QUEST AUTHENTICATION_MODE,
278     * or when changing to CLEAR_QUEST AUTHENTICATION_MODE, this property
279     * specifies the new ClearQuest password.
280     * 
281     * @param password A String containing the new value for the authenticator
282     *            associated with this user.
283     */
284    void setAuthenticator(String password);
285
286    /**
287     * The phone number field from this user's profile.
288     */
289    static PropertyName<String> PHONE =
290        new PropertyName<String>(PROPERTY_NAMESPACE, "phone");
291
292    /**
293     * Returns the value of the {@link #PHONE PHONE} property as defined by this
294     * proxy.
295     * 
296     * @return A String containing the phone field of this user's profile. Will
297     *         never be <b>null</b>.
298     * 
299     * @throws WvcmException if this proxy does not define a value for the
300     *             {@link #PHONE PHONE} property.
301     */
302    String getPhone() throws WvcmException;
303
304    /**
305     * Defines a new value for the {@link #PHONE PHONE} property of this proxy.
306     * 
307     * @param phone A String containing the new value for the phone field of
308     *            this user's profile
309     */
310    void setPhone(String phone);
311
312    /**
313     * The databases to which the user is subscribed. If the user is subscribed
314     * to all databases, this list will contain all databases.
315     */
316    static PropertyName<ResourceList<CqUserDb>> SUBSCRIBED_DATABASES =
317        new PropertyName<ResourceList<CqUserDb>>(PROPERTY_NAMESPACE,
318                                                 "subscribed-databases");
319
320    /**
321     * Returns the value of the
322     * {@link #SUBSCRIBED_DATABASES SUBSCRIBED_DATABASES} property as defined by
323     * this proxy.
324     * 
325     * @return A ResourceList containing a CqUserDb resource for each user
326     *         database to which this group is subscribed. Will never be <b>null</b>.
327     * 
328     * @throws WvcmException if this proxy does not define a value for the
329     *             {@link #SUBSCRIBED_DATABASES SUBSCRIBED_DATABASES} property.
330     */
331    ResourceList<CqUserDb> getSubscribedDatabases() throws WvcmException;
332
333    /**
334     * Defines a new value for the
335     * {@link #SUBSCRIBED_DATABASES SUBSCRIBED_DATABASES} property of this
336     * proxy.
337     * 
338     * @param value A ResourceList containing a CqUserDb proxy for each user
339     *            database to which this user is now subscribed. May be <b>null</b>
340     *            or empty to unsubscribe the user from all user databases.
341     */
342    void setSubscribedDatabases(ResourceList<CqUserDb> value);
343
344    /**
345     * Establishes the values to be added to and/or deleted from the
346     * SUBSCRIBED_DATABASES property when that property is updated from this
347     * proxy (via doWriteProperties or any other "do" method of this interface).
348     * 
349     * @param additions The list of CqUserDb proxies that must be in the
350     *            SUBSCRIBED_DATABASES property after it has been updated from
351     *            this proxy. Thus, it is OK for a value in this list to already
352     *            be a member of the property value. This list may be empty or
353     *            null if no values are to be added to the property. A value may
354     *            not appear in both this list and the deletions list.
355     * 
356     * @param deletions The list of CqUserDb proxies that must not be in the
357     *            SUBSCRIBED_DATABASES property after it has been updated from
358     *            this proxy. Thus, it is OK for a value in this list to not be
359     *            a current member of the property value. This list may be empty
360     *            or null if no values are to be deleted from the property. A
361     *            value may not appear in both this list and the additions list.
362     */
363    void setSubscribedDatabases(ResourceList<CqUserDb> additions,
364                                ResourceList<CqUserDb> deletions);
365
366    /**
367     * Indication of whether or not this user's account is active
368     */
369    static PropertyName<Boolean> IS_ACTIVE =
370        new PropertyName<Boolean>(PROPERTY_NAMESPACE, "is-active");
371
372    /**
373     * Returns the value of the {@link #IS_ACTIVE IS_ACTIVE} property as defined
374     * by this proxy.
375     * 
376     * @return <b>true</b> if the user is active; <b>false</b> if not.
377     * 
378     * @throws WvcmException if this proxy does not define a value for the
379     *             {@link #CQ_MASTER_REPLICA CQ_MASTER_REPLICA} property.
380     */
381    boolean getIsActive() throws WvcmException;
382
383    /**
384     * Defines a new value for the {@link #IS_ACTIVE IS_ACTIVE} property of this
385     * proxy.
386     * 
387     * @param active <b>true</b> to make this user active; <b>false</b> to
388     *            make the user inactive.
389     */
390    void setIsActive(boolean active);
391
392    /**
393     * The value of this property is an StpProperty.List containing an
394     * StpProperty&lt;Boolean&gt; object for each user privilege defined by
395     * ClearQuest. The Boolean value of each property indicates whether or not
396     * this user has the privilege denoted by the property. The properties that
397     * appear in this list are determined by the UserPrivilegeMaskType
398     * enumeration defined by ClearQuest. The values in this enumeration known
399     * at the time of release are defined by this API specification; others may
400     * be subsequently defined and, if so, will also appear in this list.
401     * <p>
402     * Any of the privileges enumerated in the USER_PRIVILEGES property can be
403     * granted or denied to the user by using Resource.setProperty to assign the
404     * particular property either Boolean.TRUE or Boolean.FALSE.
405     */
406    static PropertyName<List<StpProperty<Boolean>>> USER_PRIVILEGES =
407        new PropertyName<List<StpProperty<Boolean>>>(PROPERTY_NAMESPACE,
408                                                     "user-privileges");
409
410    /**
411     * Returns the value of the {@link #USER_PRIVILEGES USER_PRIVILEGES}
412     * property as defined by this proxy.
413     * 
414     * @return A List containing one StpProperty object for each privilege
415     *         defined by ClearQuest. Will never be <b>null</b>.
416     * 
417     * @throws WvcmException if this proxy does not define a value for the
418     *             {@link #USER_PRIVILEGES USER_PRIVILEGES} property.
419     */
420    List<StpProperty<Boolean>> getUserPrivileges() throws WvcmException;
421
422    /**
423     * Answers whether or not this user can create and manage dynamic lists.
424     */
425    static PropertyName<Boolean> IS_DYNAMIC_LIST_ADMIN =
426        new PropertyName<Boolean>(PROPERTY_NAMESPACE, "is-dynamic-list-admin");
427
428    /**
429     * Returns the value of the
430     * {@link #IS_DYNAMIC_LIST_ADMIN IS_DYNAMIC_LIST_ADMIN} property as defined
431     * by this proxy.
432     * 
433     * @return <b>true</b> if the user is permitted to edit dynamic choice
434     *         lists; <b>false</b> if the user may not.
435     * 
436     * @throws WvcmException if this proxy does not define a value for the
437     *             {@link #IS_DYNAMIC_LIST_ADMIN IS_DYNAMIC_LIST_ADMIN}
438     *             property.
439     */
440    boolean getIsDynamicListAdmin() throws WvcmException;
441
442    /**
443     * Defines a new value for the
444     * {@link #IS_DYNAMIC_LIST_ADMIN IS_DYNAMIC_LIST_ADMIN} property of this
445     * proxy.
446     * 
447     * @param permitted <b>true</b> to permit this user to edit dynamic choice
448     *            lists; <b>false</b> to deny the user this ability.
449     */
450    void setIsDynamicListAdmin(boolean permitted);
451
452    /**
453     * Answers whether or not this user can create, delete, or update resources
454     * in the public folders heirarcy used for queries, reports, and charts.
455     */
456    static PropertyName<Boolean> IS_PUBLIC_FOLDER_ADMIN =
457        new PropertyName<Boolean>(PROPERTY_NAMESPACE, "is-public-folder-admin");
458
459    /**
460     * Returns the value of the
461     * {@link #IS_PUBLIC_FOLDER_ADMIN IS_PUBLIC_FOLDER_ADMIN} property as
462     * defined by this proxy.
463     * 
464     * @return <b>true</b> if the user is permitted to edit public folders;
465     *         <b>false</b> if the user may not.
466     * 
467     * @throws WvcmException if this proxy does not define a value for the
468     *             {@link #IS_PUBLIC_FOLDER_ADMIN IS_PUBLIC_FOLDER_ADMIN}
469     *             property.
470     */
471    boolean getIsPublicFolderAdmin() throws WvcmException;
472
473    /**
474     * Defines a new value for the
475     * {@link #IS_PUBLIC_FOLDER_ADMIN IS_PUBLIC_FOLDER_ADMIN} property of this
476     * proxy.
477     * 
478     * @param permitted <b>true</b> to permit this user to edit public folders;
479     *            <b>false</b> to deny the user this ability.
480     */
481    void setIsPublicFolderAdmin(boolean permitted);
482
483    /**
484     * Answers whether or not this user can access and manage secure records and
485     * fields as well as edit the context group list field for a security context
486     * record and view all records.
487     */
488    static PropertyName<Boolean> IS_SECURITY_ADMIN =
489        new PropertyName<Boolean>(PROPERTY_NAMESPACE, "is-security-admin");
490
491    /**
492     * Returns the value of the {@link #IS_SECURITY_ADMIN IS_SECURITY_ADMIN}
493     * property as defined by this proxy.
494     * 
495     * @return <b>true</b> if the user is permitted to edit security
496     *         components; <b>false</b> if the user may not.
497     * 
498     * @throws WvcmException if this proxy does not define a value for the
499     *             {@link #IS_SECURITY_ADMIN IS_SECURITY_ADMIN } property.
500     */
501    boolean getIsSecurityAdmin() throws WvcmException;
502
503    /**
504     * Defines a new value for the {@link #IS_SECURITY_ADMIN IS_SECURITY_ADMIN }
505     * property of this proxy.
506     * 
507     * @param permitted <b>true</b> to permit this user to edit security
508     *            components; <b>false</b> to deny the user this ability.
509     */
510    void setIsSecurityAdmin(boolean permitted);
511
512    /**
513     * Answers whether or not this user can create (either from scratch or
514     * through modification of an existing query) a query defined by a raw SQL
515     * string.
516     */
517    static PropertyName<Boolean> IS_RAW_SQL_WRITER =
518        new PropertyName<Boolean>(PROPERTY_NAMESPACE, "is-raw-sql-writer");
519
520    /**
521     * Returns the value of the {@link #IS_RAW_SQL_WRITER IS_RAW_SQL_WRITER }
522     * property as defined by this proxy.
523     * 
524     * @return <b>true</b> if the user is permitted to edit raw SQL in queries;
525     *         <b>false</b> if the user may not.
526     * 
527     * @throws WvcmException if this proxy does not define a value for the
528     *             {@link #IS_RAW_SQL_WRITER IS_RAW_SQL_WRITER } property.
529     */
530    boolean getIsRawSqlWriter() throws WvcmException;
531
532    /**
533     * Defines a new value for the {@link #IS_RAW_SQL_WRITER IS_RAW_SQL_WRITER }
534     * property of this proxy.
535     * 
536     * @param permitted <b>true</b> to permit this user to edit raw SQL in
537     *            queries; <b>false</b> to deny the user this ability.
538     */
539    void setIsRawSqlWriter(boolean permitted);
540
541    /**
542     * Answers whether or not this user can view information about all users and
543     * groups in user databases.
544     */
545    static PropertyName<Boolean> IS_ALL_USERS_VISIBLE =
546        new PropertyName<Boolean>(PROPERTY_NAMESPACE, "is-all-users-visible");
547
548    /**
549     * Returns the value of the
550     * {@link #IS_ALL_USERS_VISIBLE IS_ALL_USERS_VISIBLE } property as defined
551     * by this proxy.
552     * 
553     * @return <b>true</b> if the user is permitted to see all users and groups; <b>false</b>
554     *         if the user may not.
555     * 
556     * @throws WvcmException if this proxy does not define a value for the
557     *             {@link #IS_ALL_USERS_VISIBLE IS_ALL_USERS_VISIBLE } property.
558     */
559    boolean getIsAllUsersVisible() throws WvcmException;
560
561    /**
562     * Defines a new value for the
563     * {@link #IS_ALL_USERS_VISIBLE IS_ALL_USERS_VISIBLE } property of this
564     * proxy.
565     * 
566     * @param permitted <b>true</b> to permit this user to see all users;
567     *            <b>false</b> to deny the user this ability.
568     */
569    void setIsAllUsersVisible(boolean permitted);
570
571    /**
572     * Answers whether or not this user has multisite administrator privileges.
573     */
574    static PropertyName<Boolean> IS_MULTI_SITE_ADMIN =
575        new PropertyName<Boolean>(PROPERTY_NAMESPACE, "is-multi-site-admin");
576
577    /**
578     * Returns the value of the
579     * {@link #IS_MULTI_SITE_ADMIN IS_MULTI_SITE_ADMIN } property as defined by
580     * this proxy.
581     * 
582     * @return <b>true</b> if the user is permitted to edit multisite
583     *         components; <b>false</b> if the user may not.
584     * 
585     * @throws WvcmException if this proxy does not define a value for the
586     *             {@link #IS_MULTI_SITE_ADMIN IS_MULTI_SITE_ADMIN } property.
587     */
588    boolean getIsMultiSiteAdmin() throws WvcmException;
589
590    /**
591     * Defines a new value for the
592     * {@link #IS_MULTI_SITE_ADMIN IS_MULTI_SITE_ADMIN } property of this proxy.
593     * 
594     * @param permitted <b>true</b> to permit this user to edit multi-site
595     *            components; <b>false</b> to deny the user this ability.
596     */
597    void setIsMultiSiteAdmin(boolean permitted);
598
599    /**
600     * Answers whether or not this user has been granted all privileges and can
601     * also create and delete databases and schemas and edit ClearQuest Web
602     * settings. The administrator account has this privilege.
603     */
604    static PropertyName<Boolean> IS_SUPER_USER =
605        new PropertyName<Boolean>(PROPERTY_NAMESPACE, "is-super-user");
606
607    /**
608     * Returns the value of the {@link #IS_SUPER_USER IS_SUPER_USER } property
609     * as defined by this proxy.
610     * 
611     * @return <b>true</b> if the user is permitted to be super user; <b>false</b>
612     *         if the user may not.
613     * 
614     * @throws WvcmException if this proxy does not define a value for the
615     *             {@link #IS_SUPER_USER IS_SUPER_USER } property.
616     */
617    boolean getIsSuperUser() throws WvcmException;
618
619    /**
620     * Defines a new value for the {@link #IS_SUPER_USER } property of this
621     * proxy.
622     * 
623     * @param permitted <b>true</b> to permit this user to be super user;
624     *            <b>false</b> to deny the user this ability.
625     */
626    void setIsSuperUser(boolean permitted);
627
628    /**
629     * Answers whether or not this user can create and modify schemas, update
630     * existing databases, and create, modify, and save public queries, charts, and
631     * reports (but not perform user administrator tasks).
632     */
633    PropertyName<Boolean> IS_APP_BUILDER =
634        new PropertyName<Boolean>(PROPERTY_NAMESPACE, "is-app-builder");
635
636    /**
637     * Returns the value of the {@link #IS_APP_BUILDER IS_APP_BUILDER } property
638     * as defined by this proxy.
639     * 
640     * @return <b>true</b> if the user is permitted to edit schemas; <b>false</b>
641     *         if the user may not.
642     * 
643     * @throws WvcmException if this proxy does not define a value for the
644     *             {@link #IS_APP_BUILDER IS_APP_BUILDER } property.
645     */
646    boolean getIsAppBuilder() throws WvcmException;
647
648    /**
649     * Defines a new value for the {@link #IS_APP_BUILDER IS_APP_BUILDER }
650     * property of this proxy.
651     * 
652     * @param permitted <b>true</b> to permit this user to edit schemas;
653     *            <b>false</b> to deny the user this ability.
654     */
655    void setIsAppBuilder(boolean permitted);
656
657    /**
658     * Answers whether or not this user can create users and user groups and
659     * assign and modify their user-access privileges.
660     */
661    PropertyName<Boolean> IS_USER_MAINTAINER =
662        new PropertyName<Boolean>(PROPERTY_NAMESPACE, "is-user-maintainer");
663
664    /**
665     * Returns the value of the {@link #IS_USER_MAINTAINER IS_USER_MAINTAINER }
666     * property as defined by this proxy.
667     * 
668     * @return <b>true</b> if the user is permitted to edit user and groups
669     *         artifacts; <b>false</b> if the user may not.
670     * 
671     * @throws WvcmException if this proxy does not define a value for the
672     *             {@link #IS_USER_MAINTAINER IS_USER_MAINTAINER } property.
673     */
674    boolean getIsUserMaintainer() throws WvcmException;
675
676    /**
677     * Defines a new value for the
678     * {@link #IS_USER_MAINTAINER IS_USER_MAINTAINER } property of this proxy.
679     * 
680     * @param permitted <b>true</b> to permit this user to edit user and group
681     *            artifacts; <b>false</b> to deny the user this ability.
682     */
683    void setIsUserMaintainer(boolean permitted);
684
685    /**
686     * Answers whether or not this user is automatically subscribed to all
687     * databases of the DbSet.
688     */
689    static PropertyName<Boolean> IS_SUBSCRIBED_TO_ALL_DATABASES =
690        new PropertyName<Boolean>(PROPERTY_NAMESPACE,
691                                  "is-subscribed-to-all-databases");
692
693    /**
694     * Returns the value of the
695     * {@link #IS_SUBSCRIBED_TO_ALL_DATABASES IS_SUBSCRIBED_TO_ALL_DATABASES }
696     * property as defined by this proxy.
697     * 
698     * @return <b>true</b> if the user is subscribed to all databases; <b>false</b>
699     *         if the user is subscribed only to those databases enumerated on
700     *         the SUBSCRIBED_DATABASES list.
701     * 
702     * @throws WvcmException if this proxy does not define a value for the
703     *             {@link #IS_SUBSCRIBED_TO_ALL_DATABASES IS_SUBSCRIBED_TO_ALL_DATABASES }
704     *             property.
705     */
706    boolean getIsSubscribedToAllDatabases() throws WvcmException;
707
708    /**
709     * Defines a new value for the
710     * {@link #IS_SUBSCRIBED_TO_ALL_DATABASES IS_SUBSCRIBED_TO_ALL_DATABASES }
711     * property of this proxy.
712     * 
713     * @param permitted <b>true</b> to automatically subscribe the user to all
714     *            databases current and future; <b>false</b> to require the
715     *            user to subscribe to each database individually.
716     */
717    void setIsSubscribedToAllDatabases(boolean permitted);
718
719    /**
720     * The replica that masters this user
721     */
722    PropertyName<CqReplica> CQ_MASTER_REPLICA =
723        new PropertyName<CqReplica>(PROPERTY_NAMESPACE, "cq-master-replica");
724
725    /**
726     * Returns the value of the {@link #CQ_MASTER_REPLICA CQ_MASTER_REPLICA} property
727     * as defined by this proxy.
728     * 
729     * @return A CqReplica proxy for the replica that masters this user. Will
730     *         never be <b>null</b>.
731     * 
732     * @throws WvcmException if this proxy does not define a value for the
733     *             {@link #CQ_MASTER_REPLICA CQ_MASTER_REPLICA} property.
734     */
735    CqReplica getCqMasterReplica() throws WvcmException;
736
737    /**
738     * Defines a new value for the {@link #CQ_MASTER_REPLICA CQ_MASTER_REPLICA}
739     * property of this proxy.
740     * 
741     * @param value A CqReplica proxy specifying the replica that is to assume
742     *            mastership of this user resource.
743     */
744    void setCqMasterReplica(CqReplica value);
745
746    /**
747     * Creates a new user whose ClearQuest login name will be the same as the
748     * Name field of this proxy's location. The new user is created in the DbSet
749     * named by the Repo field of that location. The location is of the form
750     * 
751     * <pre>
752     * cq.user:&lt;login-name>@&lt;db-set-name>
753     * </pre>
754     * 
755     * If the LOGIN_NAME property is not set, it will default to the Name field
756     * of this proxy's location.
757     * <p>
758     * If the AUTHENTICATION_MODE is CLEAR_QUEST, the value of the LOGIN_NAME
759     * property of this proxy, if set, is ignored and forced to be the same as
760     * the Name field of this proxy's location. The AUTHENTICATOR should be the
761     * user's ClearQuest password.
762     * <p>
763     * If the AUTHENTICATION_MODE is LDAP, then the AUTHENTICATOR should be set
764     * to the LDAP authentication name that is to correspond to this user. An
765     * LDAP attribute value is copied from the LDAP user account to a ClearQuest
766     * user profile field as specified by the value of
767     * {@link CqDb#LDAP_PROPERTY}. This method first checks the DbSet to ensure
768     * that there is no conflict with another active LDAP-enabled user's
769     * LDAP_PROPERTY value to ensure that the values are unique across active
770     * LDAP enabled users. If the LDAP_PROPERTY is LOGIN_NAME_FIELD, the
771     * login-name must be identical to LOGIN_NAME.
772     * 
773     * @param feedback Specifies optional feedback to the caller.
774     * @return A proxy for this new resource, whose properties are specified by
775     *         feedback.
776     * @throws WvcmException ReasonCode:
777     *             <li>{@link javax.wvcm.WvcmException.ReasonCode#RESOURCE_ALREADY_EXISTS_AT_LOCATION RESOURCE_ALREADY_EXISTS_AT_LOCATION}:
778     *             If a resource already exists at the location of this
779     *             Resource, the request MUST fail.
780     *             <li>{@link javax.wvcm.WvcmException.ReasonCode#CANNOT_CREATE_AT_THIS_LOCATION CANNOT_CREATE_AT_THIS_LOCATION}:
781     *             If the location of this Group does not identify a valid
782     *             location in which to create a group, the request MUST fail.
783     *             Groups must be created in a DbSet
784     */
785    CqUser doCreateUser(Feedback feedback) throws WvcmException;
786
787    /**
788     * Attempts to upgrade the user account information in all the user
789     * databases that this user is currently subscribed to.
790     * 
791     * Any dirty properties of this proxy are written to the DbSet before the
792     * upgrading of user databases is attempted. If the property updates fail,
793     * no attempt is made to upgrade the subscribed databases.
794     * 
795     * @param feedback Specifies optional feedback to the caller. The databases
796     *            being upgraded are considered to be resources modified by this
797     *            operation and will generate calls to
798     *            {@link javax.wvcm.DetailedFeedback#notifyIsModified(javax.wvcm.Resource)}
799     *            if requested.
800     * @return A proxy for this resource after the upgrade is complete, with
801     *         properties as specified by feedback.
802     * @throws WvcmException if any dirty properties could not be updated.
803     * @throws StpPartialResultsException if any of the subscribed databases
804     *             could not be upgraded, with the failed updates indicated by
805     *             nested exceptions of this exception.
806     */
807    CqUser doUpgradeDatabases(Feedback feedback) throws WvcmException;
808}