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>&lt;group-name&gt;</i>@<i>&lt;db-set&gt;</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:&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    }