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 * (C) Copyright IBM Corporation 2006, 2014.  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
014package com.ibm.rational.wvcm.stp.cq;
015
016import static com.ibm.rational.wvcm.stpex.StpExBase.PROPERTY_NAMESPACE;
017
018import javax.wvcm.Feedback;
019import javax.wvcm.ResourceList;
020import javax.wvcm.WvcmException;
021import javax.wvcm.PropertyNameList.PropertyName;
022
023import com.ibm.rational.wvcm.stp.StpPrincipal;
024import com.ibm.rational.wvcm.stp.StpResource;
025import 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>&lt;group-name&gt;</i>@<i>&lt;db-set&gt;</i>
038 * </pre>
039 */
040public 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 groups attributes. Access to a database is
061     * permitted if the user belongs to another group that has access or if the
062     * users 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:&lt;group-name>@&lt;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}