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 }