001 /*
002 * file CqGroup.java
003 *
004 * Licensed Materials - Property of IBM
005 * Restricted Materials of IBM
006 *
007 * com.ibm.rational.wvcm.stp.cq.CqGroup
008 *
009 * © Copyright IBM Corporation 2006, 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.stp.StpPrincipal;
024 import com.ibm.rational.wvcm.stp.StpResource;
025 import com.ibm.rational.wvcm.stpex.StpExBase;
026
027 /**
028 * Interface for ClearQuest group resources.
029 * <p>
030 * Changes you make to a group are immediately reflected in the db-set (schema
031 * repository, master database) but not the associated user databases. To update
032 * the user databases, apply {@link CqUserDb#doUpgradeUsersAndGroups(Feedback)}
033 * on each database individually.
034 * <p>
035 * The user-friendly specification for the location of a group has the form
036 * <pre>
037 * <b>cq.group:</b><i><group-name></i>@<i><db-set></i>
038 * </pre>
039 */
040 public interface CqGroup extends CqResource, StpPrincipal
041 {
042 /** The database set that contains this resource */
043 PropertyName<CqDbSet> DB_SET =
044 new PropertyName<CqDbSet>(PROPERTY_NAMESPACE, "db-set");
045
046 /**
047 * Returns the value of the {@link #DB_SET DB_SET} property as defined by
048 * this proxy.
049 *
050 * @return A CqDbSet proxy for the database set that contains this resource.
051 *
052 * @throws WvcmException if this proxy does not define a value for the
053 * {@link #DB_SET DB_SET} property.
054 */
055 CqDbSet getDbSet() throws WvcmException;
056
057 /**
058 * Indicates whether or not the group is active. This property can be
059 * retrieved or set. Members of an inactive group are not allowed to access
060 * any databases using the group’s attributes. Access to a database is
061 * permitted if the user belongs to another group that has access or if the
062 * user’s account is specifically subscribed to the database.
063 */
064 PropertyName<Boolean> IS_ACTIVE =
065 new PropertyName<Boolean>(PROPERTY_NAMESPACE, "is-active");
066
067 /**
068 * Returns the value of the {@link #IS_ACTIVE IS_ACTIVE} property as defined
069 * by this proxy.
070 *
071 * @return <b>true</b> if the group is active; <b>false</b> otherwise.
072 *
073 * @throws WvcmException if this proxy does not define a value for the
074 * {@link #IS_ACTIVE IS_ACTIVE} property.
075 */
076 boolean getIsActive() throws WvcmException;
077
078 /**
079 * Defines a new value for the {@link #IS_ACTIVE IS_ACTIVE} property of this
080 * proxy.
081 *
082 * @param value <b>true</b> to make the group active; <b>false</b> to make
083 * it inactive.
084 */
085 void setIsActive(boolean value);
086
087 /**
088 * Returns the databases to which this group may subscribe, including
089 * databases to which it is already described.
090 */
091 PropertyName<ResourceList<CqUserDb>> ALL_DATABASES =
092 new PropertyName<ResourceList<CqUserDb>>(PROPERTY_NAMESPACE,
093 "all-databases");
094
095 /**
096 * Returns the value of the {@link #ALL_DATABASES ALL_DATABASES} property as
097 * defined by this proxy.
098 *
099 * @return A ResourceList containing a CqUserDb proxy for each database to
100 * which this group may subscribe. Will never be <b>null</b>.
101 *
102 * @throws WvcmException if this proxy does not define a value for the
103 * {@link #ALL_DATABASES ALL_DATABASES} property.
104 */
105 ResourceList<CqUserDb> getAllDatabases() throws WvcmException;
106
107 /**
108 * Indicates whether this Group is subscribed to all databases in a Db-set
109 * (schema repository, master database).
110 */
111 PropertyName<Boolean> IS_SUBSCRIBED_TO_ALL_DATABASES =
112 new PropertyName<Boolean>(PROPERTY_NAMESPACE,
113 "is-subscribed-to-all-databases");
114
115 /**
116 * Returns the value of the
117 * {@link #IS_SUBSCRIBED_TO_ALL_DATABASES IS_SUBSCRIBED_TO_ALL_DATABASES}
118 * property as defined by this proxy.
119 *
120 * @return <b>true</b> if the Group is subscribed to all databases in the
121 * d, <b>false</b> otherwise.
122 *
123 * @throws WvcmException if this proxy does not define a value for the
124 * {@link #IS_SUBSCRIBED_TO_ALL_DATABASES IS_SUBSCRIBED_TO_ALL_DATABASES}
125 * property.
126 */
127 boolean getIsSubscribedToAllDatabases() throws WvcmException;
128
129 /**
130 * Defines a new value for the
131 * {@link #IS_SUBSCRIBED_TO_ALL_DATABASES IS_SUBSCRIBED_TO_ALL_DATABASES}
132 * property of this proxy.
133 *
134 * @param value <b>true</b> if this group is henceforth to be subscribed to
135 * all db-set databases; <b>false</b> if it is to be subscribed
136 * only to the databases on its SUBCRIBED_DATABASES list.
137 */
138 void setIsSubscribedToAllDatabases(boolean value);
139
140 /**
141 * The replica that masters this group
142 */
143 PropertyName<CqReplica> CQ_MASTER_REPLICA =
144 new PropertyName<CqReplica>(PROPERTY_NAMESPACE, "cq-master-replica");
145
146 /**
147 * Returns the value of the {@link #CQ_MASTER_REPLICA CQ_MASTER_REPLICA}
148 * property as defined by this proxy.
149 *
150 * @return A CqReplica proxy for the replica that masters this group
151 * resource. Will never be <b>null</b>.
152 *
153 * @throws WvcmException if this proxy does not define a value for the
154 * {@link #CQ_MASTER_REPLICA CQ_MASTER_REPLICA} property.
155 */
156 CqReplica getCqMasterReplica() throws WvcmException;
157
158 /**
159 * Defines a new value for the {@link #CQ_MASTER_REPLICA CQ_MASTER_REPLICA}
160 * property of this proxy.
161 *
162 * @param value A CqReplica proxy for the replica that is to assume
163 * mastership of this group.
164 */
165 void setCqMasterReplica(CqReplica value);
166
167 /**
168 * The user databases to which this group is subscribed. If
169 * {@link #getIsSubscribedToAllDatabases()} is true, then this list will
170 * include all databases.
171 */
172 PropertyName<ResourceList<CqUserDb>> SUBSCRIBED_DATABASES =
173 new PropertyName<ResourceList<CqUserDb>>(PROPERTY_NAMESPACE,
174 "subscribed-databases");
175
176 /**
177 * Returns the value of the
178 * {@link #SUBSCRIBED_DATABASES SUBSCRIBED_DATABASES} property as defined by
179 * this proxy.
180 *
181 * @return A ResourceList containing a CqUserDb resource for each user
182 * database to which this group is explicitly or implicitly
183 * subscribed. Will never be <b>null</b>.
184 *
185 * @throws WvcmException if this proxy does not define a value for the
186 * {@link #SUBSCRIBED_DATABASES SUBSCRIBED_DATABASES} property.
187 */
188 ResourceList<CqUserDb> getSubscribedDatabases() throws WvcmException;
189
190 /**
191 * Defines a new value for the
192 * {@link #SUBSCRIBED_DATABASES SUBSCRIBED_DATABASES} property of this
193 * proxy.
194 *
195 * @param value A ResourceList containing a CqUserDb proxy for each user
196 * database to which this group is now subscribed. May be <b>null</b>
197 * or empty to unsubscribe the group from all user databases.
198 */
199 void setSubscribedDatabases(ResourceList<CqUserDb> value);
200
201 /**
202 * Establishes the values to be added to and/or deleted from the
203 * SUBSCRIBED_DATABASES property when that property is updated from this
204 * proxy (via doWriteProperties or any other "do" method of this interface).
205 *
206 * @param additions The list of CqUserDb proxies that must be in the
207 * SUBSCRIBED_DATABASES property after it has been updated from
208 * this proxy. Thus, it is OK for a value in this list to already
209 * be a member of the property value. This list may be empty or
210 * null if no values are to be added to the property. A value may
211 * not appear in both this list and the deletions list.
212 *
213 * @param deletions The list of CqUserDb proxies that must not be in the
214 * SUBSCRIBED_DATABASES property after it has been updated from
215 * this proxy. Thus, it is OK for a value in this list to not be
216 * a current member of the property value. This list may be empty
217 * or null if no values are to be deleted from the property. A
218 * value may not appear in both this list and the additions list.
219 */
220 void setSubscribedDatabases(ResourceList<CqUserDb> additions,
221 ResourceList<CqUserDb> deletions);
222
223 /**
224 * The users that belong to this group
225 */
226 PropertyName<ResourceList<CqUser>> USERS =
227 new PropertyName<ResourceList<CqUser>>(PROPERTY_NAMESPACE, "users");
228
229 /**
230 * Returns the value of the {@link #USERS USERS} property as defined by this
231 * proxy. If this property was set via
232 * {@link #setSubscribedDatabases(ResourceList, ResourceList)} this method
233 * returns only the list of additions.
234 *
235 * @return A ResourceList containing a CqUser proxy for each user that is
236 * the member of this group. Will never be <b>null</b>.
237 *
238 * @throws WvcmException if this proxy does not define a value for the
239 * {@link #USERS USERS} property.
240 */
241 ResourceList<CqUser> getUsers() throws WvcmException;
242
243 /**
244 * Defines a new value for the {@link #USERS USERS} property of this proxy.
245 *
246 * @param value A ResourceList containing a CqUser proxy for each user that
247 * is to be a member of this group.
248 */
249 void setUsers(ResourceList<CqUser> value);
250
251 /**
252 * Establishes the values to be added to and/or deleted from the USERS
253 * property when that property is updated from this proxy (via
254 * doWriteProperties or any other "do" method of this interface).
255 *
256 * @param additions The list of CqUser proxies that must be in the USERS
257 * property after it has been updated from this proxy. Thus, it
258 * is OK for a value in this list to already be a member of the
259 * property value. This list may be empty or null if no values
260 * are to be added to the property. A value may not appear in
261 * both this list and the deletions list.
262 *
263 * @param deletions The list of CqUser proxies that must not be in the USERS
264 * property after it has been updated from this proxy. Thus, it
265 * is OK for a value in this list to not be a current member of
266 * the property value. This list may be empty or null if no
267 * values are to be deleted from the property. A value may not
268 * appear in both this list and the additions list.
269 */
270 void setUsers(ResourceList<CqUser> additions,
271 ResourceList<CqUser> deletions);
272
273 /**
274 * The groups that belong to this group
275 */
276 PropertyName<ResourceList<CqGroup>> GROUPS =
277 new PropertyName<ResourceList<CqGroup>>(PROPERTY_NAMESPACE, "groups");
278
279 /**
280 * Returns the value of the {@link #GROUPS GROUPS} property as defined by
281 * this proxy. If this property was set via
282 * {@link #setSubscribedDatabases(ResourceList, ResourceList)} this method
283 * returns only the list of additions.
284 *
285 * @return A ResourceList containing a CqGroup proxy for each group that is
286 * the member of this group. Will never be <b>null</b>.
287 *
288 * @throws WvcmException if this proxy does not define a value for the
289 * {@link #GROUPS GROUPS} property.
290 */
291 ResourceList<CqGroup> getGroups() throws WvcmException;
292
293 /**
294 * Defines a new value for the {@link #GROUPS GROUPS} property of this
295 * proxy.
296 *
297 * @param value A ResourceList containing a CqGroup proxy for each group
298 * that is to be a member of this group.
299 */
300 void setGroups(ResourceList<CqGroup> value);
301
302 /**
303 * Establishes the values to be added to and/or deleted from the GROUPS
304 * property when that property is updated from this proxy (via
305 * doWriteProperties or any other "do" method of this interface).
306 *
307 * @param additions The list of CqGroup proxies that must be in the GROUPS
308 * property after it has been updated from this proxy. Thus, it
309 * is OK for a value in this list to already be a member of the
310 * property value. This list may be empty or null if no values
311 * are to be added to the property. A value may not appear in
312 * both this list and the deletions list.
313 *
314 * @param deletions The list of CqGroup proxies that must not be in the
315 * GROUPS property after it has been updated from this proxy.
316 * Thus, it is OK for a value in this list to not be a current
317 * member of the property value. This list may be empty or null
318 * if no values are to be deleted from the property. A value may
319 * not appear in both this list and the additions list.
320 */
321 void setGroups(ResourceList<CqGroup> additions,
322 ResourceList<CqGroup> deletions);
323
324 /**
325 * Creates a new group and associates it with the DbSet named by the proxy
326 * location. The location is of the form
327 *
328 * <pre>
329 * cq.group:<group-name>@<db-set-name>
330 * </pre>
331 *
332 * The new group is subscribed to all databases by default. When you use the
333 * methods of the Group object to add users and subscribe the group to one
334 * or more databases, the groups or users are subscribed only to those you
335 * specify.
336 *
337 * @param feedback Specifies optional feedback to the caller.
338 * @return A proxy for this new resource, whose properties are specified by
339 * feedback.
340 * @throws WvcmException ReasonCode:
341 * <li>{@link javax.wvcm.WvcmException.ReasonCode#RESOURCE_ALREADY_EXISTS_AT_LOCATION CANNOT_CREATE_AT_THIS_LOCATION}:
342 * If a resource already exists at the location of this
343 * Resource, the request MUST fail.
344 * <li>{@link javax.wvcm.WvcmException.ReasonCode#CANNOT_CREATE_AT_THIS_LOCATION CANNOT_CREATE_AT_THIS_LOCATION}:
345 * If the location of this Group does not identify a valid
346 * location in which to create a group, the request MUST fail.
347 * Groups must be created in a DbSet
348 */
349 CqGroup doCreateGroup(Feedback feedback) throws WvcmException;
350 }