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