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 }