001 /* 002 * file CqQueryFolder.java 003 * 004 * Licensed Materials - Property of IBM 005 * Restricted Materials of IBM 006 * 007 * com.ibm.rational.wvcm.stp.cq.CqQueryFolder 008 * 009 * © Copyright IBM Corporation 2004, 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 java.util.EnumSet; 019 import java.util.List; 020 021 import javax.wvcm.Activity; 022 import javax.wvcm.ControllableResource; 023 import javax.wvcm.Feedback; 024 import javax.wvcm.Folder; 025 import javax.wvcm.Resource; 026 import javax.wvcm.ResourceList; 027 import javax.wvcm.Version; 028 import javax.wvcm.Workspace; 029 import javax.wvcm.WvcmException; 030 import javax.wvcm.Folder.RebindFlag; 031 import javax.wvcm.PropertyNameList.PropertyName; 032 import javax.wvcm.WvcmException.ReasonCode; 033 034 import com.ibm.rational.wvcm.stp.StpAccessControlEntry; 035 import com.ibm.rational.wvcm.stp.StpAccessControlledResource; 036 import com.ibm.rational.wvcm.stp.StpAccessControlEntry.EntryType; 037 import com.ibm.rational.wvcm.stpex.StpExBase; 038 039 040 /** 041 * A proxy for a query folder. 042 * <p> 043 * The user-friendly specification for the location of a query folder has the 044 * form 045 * 046 * <pre> 047 * <b>cq.query:</b><i><parent-folder-path></i>/<i><folder-name></i>@<i><db-set></i>/<i><user-db></i> 048 * </pre> 049 */ 050 public interface CqQueryFolder extends Folder, CqQueryFolderItem, 051 StpAccessControlledResource 052 { 053 /** 054 * Creates a new folder at the location specified in this proxy. 055 * 056 * @param feedback A Feedback object specifying the information desired from 057 * the new folder after it has been created. 058 * @return A proxy for the newly-created folder populated with the requested 059 * properties. The creation of the new folder will have been 060 * delivered to the database before the method returns. 061 * @throws WvcmException If the folder cannot be created at the specified 062 * location. 063 */ 064 CqQueryFolder doCreateFolder(Feedback feedback) throws WvcmException; 065 066 /** 067 * Creates a new folder at the location specified in this proxy. 068 * 069 * @param feedback A Feedback object specifying the information desired from 070 * the new folder after it has been created. 071 * @param deliveryOrder A specification of what resources are to be 072 * delivered to the database after the folder has been created. 073 * @return A proxy for the newly-created folder populated with the requested 074 * properties. 075 * @throws WvcmException If the folder cannot be created at the specified 076 * location or if any of the resources to be delivered to the 077 * database cannot be delivered. 078 */ 079 CqQueryFolder doCreateFolder(Feedback feedback, 080 List<CqContextResource> deliveryOrder) 081 throws WvcmException; 082 083 /** 084 * The queries, query folders and other items that are immediately contained 085 * within this folder. 086 */ 087 PropertyName<ResourceList<CqQueryFolderItem>> QUERY_FOLDER_ITEMS = 088 new PropertyName<ResourceList<CqQueryFolderItem>>(PROPERTY_NAMESPACE, 089 "query-folder-items"); 090 091 /** 092 * Returns the value of the {@link #QUERY_FOLDER_ITEMS QUERY_FOLDER_ITEMS} 093 * property as defined by this proxy. 094 * 095 * @return A ResourceList containing a proxy for each immediate member of 096 * this query folder. 097 * 098 * @throws WvcmException if this proxy does not define a value for the 099 * {@link #QUERY_FOLDER_ITEMS QUERY_FOLDER_ITEMS} property. 100 */ 101 ResourceList<CqQueryFolderItem> getQueryFolderItems() throws WvcmException; 102 103 /** 104 * A boolean indicating whether or not the effective access rights on this 105 * folder allow it to be read by the current user. 106 */ 107 PropertyName<Boolean> IS_READABLE = 108 new PropertyName<Boolean>(PROPERTY_NAMESPACE, "is-readable"); 109 110 /** 111 * Returns the value of the {@link #IS_READABLE IS_READABLE} property as 112 * defined by this proxy. 113 * 114 * @return A boolean indicating whether or not the effective access rights 115 * on this folder allow it to be read by the current user 116 * 117 * @throws WvcmException if this proxy does not define a value for the 118 * {@link #IS_READABLE IS_READABLE} property. 119 */ 120 boolean getIsReadable() throws WvcmException; 121 122 /** 123 * A boolean indicating whether or not the effective access rights on this 124 * folder allow it to be written by the current user 125 */ 126 PropertyName<Boolean> IS_WRITABLE = 127 new PropertyName<Boolean>(PROPERTY_NAMESPACE, "is-writable"); 128 129 /** 130 * Returns the value of the {@link #IS_WRITABLE IS_WRITABLE} property as 131 * defined by this proxy. 132 * 133 * @return A boolean indicating whether or not the effective access rights 134 * on this folder allow it to be read by the current user. 135 * 136 * @throws WvcmException if this proxy does not define a value for the 137 * {@link #IS_WRITABLE IS_WRITABLE} property. 138 */ 139 boolean getIsWritable() throws WvcmException; 140 141 /** 142 * A PropertyName class for requesting the applied or effective access 143 * rights for a specific group on this folder and, optionally, its nested 144 * folders 145 */ 146 public class GroupAccessRightsName extends 147 PropertyName<List<StpAccessControlEntry>> 148 { 149 /** 150 * Constructs a PropertyName for requesting the applied or effective 151 * access rights for a specific group on this folder and, optionally, 152 * its nested folders. The value of this property is a List of 153 * StpAccessControlEntry objects. 154 * 155 * @param groupName The name of the group for which access rights are to 156 * be returned. 157 * @param type The EntryType (APPLIED or EFFECTIVE) of the access rights 158 * to be returned. 159 * @param nested <b>true</b> if the access rights of the specified type 160 * and group are also to be returned for the folders nested 161 * within this folder; <b>false</b> if just the access 162 * rights on this folder are to be included. 163 */ 164 public GroupAccessRightsName(String groupName, 165 EntryType type, 166 boolean nested) 167 { 168 super(StpExBase.GROUP_ACCESS_RIGHTS_NAMESPACE, (nested? "nested-" 169 : "") 170 + type + "-" + groupName + "-access-rights"); 171 } 172 } 173 174 /** 175 * Retrieves from this proxy, the StpAccessControlEntry list returned as the 176 * value of a requested property named by a GroupAccessRightsName having the 177 * same parameters as this method. 178 * 179 * @param groupName The name of the group for which access rights were 180 * requested. 181 * @param type The EntryType of the access rights requested. 182 * @param nested <b>true</b> if the access rights of the specified type and 183 * group were also to be returned for the folders nested within 184 * this folder; <b>false</b> if just the access rights on this 185 * folder were to be included. 186 * @return A list of StpAccessControlEntry objects, each representing an 187 * AccessRight of the group as requested. 188 * @throws WvcmException If the implied GroupAccessRights property was not 189 * requested or not otherwise available. 190 */ 191 List<StpAccessControlEntry> getGroupAccessRights(String groupName, 192 EntryType type, 193 boolean nested) 194 throws WvcmException; 195 196 /** 197 * A PropertyName class for requesting the applied or effective access 198 * rights for a specific user on this folder and, optionally, its nested 199 * folders 200 */ 201 public class UserAccessRightsName extends 202 PropertyName<List<StpAccessControlEntry>> 203 { 204 /** 205 * Constructs a PropertyName for requesting the applied or effective 206 * access rights for a specific user on this folder and, optionally, its 207 * nested folders. The value of this property is a List of 208 * StpAccessControlEntry objects. 209 * 210 * @param userName The login_name of the user for which access rights 211 * are to be returned. 212 * @param type The EntryType (APPLIED or EFFECTIVE) of the access rights 213 * to be returned. 214 * @param nested <b>true</b> if the access rights of the specified type 215 * and user are also to be returned for the folders nested 216 * within this folder; <b>false</b> if just the access 217 * rights on this folder are to be included. 218 */ 219 public UserAccessRightsName(String userName, 220 EntryType type, 221 boolean nested) 222 { 223 super(StpExBase.USER_ACCESS_RIGHTS_NAMESPACE, (nested? "nested-" 224 : "") 225 + type + "-" + userName + "-access-rights"); 226 } 227 } 228 229 /** 230 * Retrieves from this proxy, the StpAccessControlEntry list returned as the 231 * value of a requested property named by a UserAccessRightsName having the 232 * same parameters as this method. 233 * 234 * @param userName The name of the user for which access rights were 235 * requested. 236 * @param type The EntryType of the access rights requested. 237 * @param nested <b>true</b> if the access rights of the specified type and 238 * user were also to be returned for the folders nested within 239 * this folder; <b>false</b> if just the access rights on this 240 * folder were to be included. 241 * @return A list of StpAccessControlEntry objects, each representing an 242 * AccessRight of the type and user as requested. 243 * @throws WvcmException If the implied GroupAccessRights property was not 244 * requested or not otherwise available. 245 */ 246 List<StpAccessControlEntry> getUserAccessRights(String userName, 247 EntryType type, 248 boolean nested) 249 throws WvcmException; 250 }