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
008package com.ibm.rational.wvcm.stp.cq;
009
010import static com.ibm.rational.wvcm.stpex.StpExBase.PROPERTY_NAMESPACE;
011
012import javax.wvcm.Feedback;
013import javax.wvcm.ResourceList;
014import javax.wvcm.WvcmException;
015import javax.wvcm.PropertyNameList.PropertyName;
016
017import 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 */
023public 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}