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