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 }