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