001    /*
002     * file CqDb.java
003     *
004     * Licensed Materials - Property of IBM
005     * Restricted Materials of IBM 
006     *
007     * com.ibm.rational.wvcm.stp.cq.CqDb
008     *
009     * (C) Copyright IBM Corporation 2007, 2008.  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    
014    package com.ibm.rational.wvcm.stp.cq;
015    
016    import static com.ibm.rational.wvcm.stpex.StpExBase.PROPERTY_NAMESPACE;
017    
018    import javax.wvcm.Feedback;
019    import javax.wvcm.ResourceList;
020    import javax.wvcm.WvcmException;
021    import javax.wvcm.PropertyNameList.PropertyName;
022    
023    import com.ibm.rational.wvcm.stpex.StpExBase;
024    
025    /**
026     * An interface for accessing administrative information regarding a
027     * login to a ClearQuest database; common to both db-sets and user databases.
028     */
029    public interface CqDb extends CqResource
030    {
031        /**
032         * Returns the string that the current user enters as the login name when
033         * authenticating. The return value may be different from a Rational
034         * ClearQuest user name if the user is LDAP authenticated. Use the
035         * CURRENT_USER property to get the Rational ClearQuest name of the user
036         * stored in the user profile record for the user. Returns the
037         * authenticating name used to access this database resource. The value
038         * returned is the name used to authenticate the user, not the Rational
039         * ClearQuest user login field name that is stored in the user profile
040         * record for the user. The return value may be an LDAP login name (for
041         * example, myname@us.ibm.com) and not a Rational ClearQuest user name (for
042         * example, mycqname).
043         */
044        PropertyName<String> AUTHENTICATION_LOGIN_NAME =
045            new PropertyName<String>(PROPERTY_NAMESPACE,
046                                     "authentication-login-name");
047    
048        /**
049         * Returns the value of the
050         * {@link #AUTHENTICATION_LOGIN_NAME AUTHENTICATION_LOGIN_NAME} property as
051         * defined by this proxy.
052         * 
053         * @return The authentication login name. Will never be <b>null</b>.
054         * 
055         * @throws WvcmException if this proxy does not define a value for the
056         *             {@link #AUTHENTICATION_LOGIN_NAME AUTHENTICATION_LOGIN_NAME}
057         *             property.
058         */
059        String getAuthenticationLoginName() throws WvcmException;
060    
061        /**
062         * Returns the CqUser structure in this database that corresponds to the
063         * logged-in user identified by the host provider.
064         */
065        PropertyName<CqUser> CURRENT_USER =
066            new PropertyName<CqUser>(PROPERTY_NAMESPACE, "current-user");
067    
068        /**
069         * Returns the value of the {@link #CURRENT_USER CURRENT_USER} property as
070         * defined by this proxy.
071         * 
072         * @return The CqUser object for the user identified by this proxy's
073         *         provider. Will never be <b>null</b>.
074         * 
075         * @throws WvcmException if this proxy does not define a value for the
076         *             {@link #CURRENT_USER CURRENT_USER} property.
077         */
078        CqUser getCurrentUser() throws WvcmException;
079    
080        /**
081         * Returns the name of the replica hosting this database.
082         */
083        PropertyName<CqReplica> LOCAL_REPLICA =
084            new PropertyName<CqReplica>(PROPERTY_NAMESPACE, "local-replica");
085    
086        /**
087         * Returns the value of the {@link #LOCAL_REPLICA LOCAL_REPLICA} property as
088         * defined by this proxy.
089         * 
090         * @return A CqReplica proxy for the local replica. Will never be <b>null</b>.
091         * 
092         * @throws WvcmException if this proxy does not define a value for the
093         *             {@link #LOCAL_REPLICA LOCAL_REPLICA} property.
094         */
095        CqReplica getLocalReplica() throws WvcmException;
096    
097        /**
098         * A list of all groups known to this database.
099         */
100        PropertyName<ResourceList<CqGroup>> ALL_GROUPS =
101            new PropertyName<ResourceList<CqGroup>>(PROPERTY_NAMESPACE,
102                                                    "all-groups");
103    
104        /**
105         * Returns the value of the {@link #ALL_GROUPS ALL_GROUPS} property as
106         * defined by this proxy.
107         * 
108         * @return The value. A list of CqGroup proxies identifying all the
109         *         groups known to the database. Will never be <b>null</b> but
110         *         the list may be empty.
111         * 
112         * @throws WvcmException if this proxy does not define a value for the
113         *             {@link #ALL_GROUPS ALL_GROUPS} property.
114         */
115        ResourceList<CqGroup> getAllGroups() throws WvcmException;
116    
117        /**
118         * A list of all users known to this database.
119         */
120        PropertyName<ResourceList<CqUser>> ALL_USERS =
121            new PropertyName<ResourceList<CqUser>>(PROPERTY_NAMESPACE, "all-users");
122    
123        /**
124         * Returns the value of the {@link #ALL_USERS ALL_USERS} property as
125         * defined by this proxy.
126         * 
127         * @return The value. A list of CqUser proxies identifying all the users
128         *         known to this database. Will never be <b>null</b>.
129         * 
130         * @throws WvcmException if this proxy does not define a value for the
131         *             {@link #ALL_USERS ALL_USERS} property.
132         */
133        ResourceList<CqUser> getAllUsers() throws WvcmException;
134    
135        /**
136         * The name of the distinguished group to which every user implicitly
137         * belongs.
138         */
139        PropertyName<String> EVERYONE_GROUP_NAME =
140            new PropertyName<String>(StpExBase.PROPERTY_NAMESPACE,
141                                     "everyone-group-name");
142    
143        /**
144         * Returns the value of the
145         * {@link #EVERYONE_GROUP_NAME EVERYONE_GROUP_NAME} property as defined
146         * by this proxy.
147         * 
148         * @return The name of the group of which every user is implicitly a
149         *         member. Will never be <b>null</b>.
150         * 
151         * @throws WvcmException if this proxy does not define a value for the
152         *             {@link #EVERYONE_GROUP_NAME EVERYONE_GROUP_NAME}
153         *             property.
154         */
155        String getEveryoneGroupName() throws WvcmException;
156    
157        /**
158         * The name of the CqUser property that is used for correlating LDAP user
159         * records to Rational ClearQuest user records; <b>null</b> if the mapping
160         * is not configured. May return an exception if there is an error
161         * connecting to the db-set associated with this database (that is, the
162         * master database or schema repository). In a MultiSite environment,
163         * Rational ClearQuest enforces that the same LDAP_PROPERTY is used for all
164         * sites (that is, the same Rational ClearQuest User field), but allows that
165         * the LDAP attribute that is mapped may be site specific. This allows you
166         * to have different LDAP schemas at different sites, but allows Rational
167         * ClearQuest to enforce the uniqueness of the Rational ClearQuest mapping
168         * field values across an entire database set. LDAP_PROPERTY is <b>null</b>
169         * if the database set has not been configured for LDAP use.
170         */
171        PropertyName<PropertyName<String>> LDAP_PROPERTY =
172            new PropertyName<PropertyName<String>>(PROPERTY_NAMESPACE,
173                                                   "ldap-property");
174        /**
175         * Returns the value of the {@link #LDAP_PROPERTY LDAP_PROPERTY} property as
176         * defined by this proxy.
177         * 
178         * @return A PropertyName identifying the property of CqUser resources that
179         *         is used for LDAP authentication or <b>null</b> if LDAP mapping
180         *         has not been configured for this database. The possible
181         *         PropertyName values are: CqUser.PHONE, CqUser.FULL_NAME,
182         *         CqUser.EMAIL, CqUser.MISCELLANEOUS_INFORMATION, and
183         *         CqUser.LOGIN_NAME.
184         * 
185         * @throws WvcmException if this proxy does not define a value for the
186         *             {@link #LDAP_PROPERTY LDAP_PROPERTY} property.
187         */
188        PropertyName<String> getLDAPProperty() throws WvcmException;
189    
190        PropertyName<String[]> DIAG_INFO = 
191        new PropertyName<String[]>(PROPERTY_NAMESPACE, "diag-info");
192    
193        /**
194         * Returns the value of the {@link #DIAG_INFO DIAG_INFO} property as defined
195         * by this proxy.
196         * 
197         * @return A String[] containing the current settings for the generation of
198         *         diagnostic information by the ClearQuest application. Will never
199         *         be <b>null</b>.
200         * 
201         * @throws WvcmException if this proxy does not define a value for the
202         *             {@link #DIAG_INFO DIAG_INFO} property.
203         */
204        String[] getDiagInfo() throws WvcmException;
205    
206    
207        /**
208         * Defines a new value for the {@link #DIAG_INFO DIAG_INFO} property of this
209         * proxy.
210         * 
211         * @param info A String[] containing the new diagnostic settings.
212         */
213        void setDiagInfo(String[] info);
214    
215    
216        /**
217         * Verifies that the provided login name and password are valid and map to
218         * the current user.
219         * 
220         * @param loginName The user's login name
221         * @param password The password associated with the loginName
222         * @param feedback A Feedback object in which may be specified the CqUser
223         *            properties to be returned in the result proxy.
224         * 
225         * @return The CqUser to which the specified credentials map if the user is
226         *         successfully validated; <b>null</b> otherwise.
227         */
228        CqUser doValidateUserCredentials(String loginName,
229                                         String password,
230                                         Feedback feedback) throws WvcmException;
231    }