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 }