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 }