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