1 package com.trendmicro.grid.acl.l0; 2 3 import com.trendmicro.grid.acl.PublicRequestContext; 4 import com.trendmicro.grid.acl.RequiredRoles; 5 import com.trendmicro.grid.acl.Service; 6 import com.trendmicro.grid.acl.l0.datatypes.*; 7 8 import javax.jws.WebMethod; 9 import javax.jws.WebParam; 10 import javax.jws.WebResult; 11 import javax.jws.WebService; 12 import javax.servlet.annotation.WebServlet; 13 import javax.xml.ws.ResponseWrapper; 14 import java.util.List; 15 16 import static com.trendmicro.grid.acl.l0.KnownRoles.*; 17 18 /** 19 * Defines public reachable services to query categories and views. 20 * 21 * @author Juergen_Kellerer, 2010-04-23 22 * @version 1.0 23 */ 24 @PublicRequestContext 25 @WebServlet("/ws/level-0/categories") 26 @WebService(targetNamespace = Level0Constants.NAMESPACE) 27 public interface PublicCategoryService extends Service { 28 29 /** 30 * Returns the names of available category views, 31 * 32 * @param locale The locale (language & country) of the requester (views are regional!). 33 * @param targetIdentifier Optional identifier specifying the requesting target application type. 34 * Is set to "default" if left empty or if it is not existing. 35 * @return A list of available view names. 36 * @throws AuthenticationException In case of this service requires authentication and the current user session 37 * is not authenticated or doesn't have the right to access the service. 38 */ 39 @WebMethod 40 @WebResult(name = "viewName") 41 @RequiredRoles(ROLE_RUN_CATEGORIZATION_QUERIES) 42 List<String> getCategoryViewNames( 43 @WebParam(name = "locale") String locale, 44 @WebParam(name = "targetIdentifier") String targetIdentifier) throws AuthenticationException; 45 46 /** 47 * @param locale The locale (language & country) of the requester. 48 * @param viewName The name of the view to return. 49 * @return The category view for the given name or 'null' if not existing. 50 * @throws AuthenticationException In case of this service requires authentication and the current user session 51 * is not authenticated or doesn't have the right to access the service. 52 */ 53 @WebMethod 54 @WebResult(name = "view") 55 @RequiredRoles(ROLE_RUN_CATEGORIZATION_QUERIES) 56 CategoryView getCategoryView( 57 @WebParam(name = "locale") String locale, 58 @WebParam(name = "viewName") String viewName) throws AuthenticationException; 59 60 /** 61 * Returns the category views for the given view names. 62 * 63 * @param locale The locale (language & country) of the requester. 64 * @param viewNames A list of view names. 65 * @return The category views for the given names. 66 * @throws AuthenticationException In case of this service requires authentication and the current user session 67 * is not authenticated or doesn't have the right to access the service. 68 */ 69 @WebMethod 70 @WebResult(name = "view") 71 @ResponseWrapper( // Adding a custom response wrapper to support 'null' values inside the returned collection. 72 className = "com.trendmicro.grid.acl.l0.wrappers.GetCategoryViewsResponse") 73 @RequiredRoles(ROLE_RUN_CATEGORIZATION_QUERIES) 74 List<CategoryView> getCategoryViews( 75 @WebParam(name = "locale") String locale, 76 @WebParam(name = "viewName") BatchCollection<String> viewNames) throws AuthenticationException; 77 78 /** 79 * Returns the plain category information (without any view or child relationship). 80 * 81 * @param locale The locale (language & country) of the requester. 82 * @param categoryName The name of the category to return. 83 * @return The plain category (without any view or child relationship). 84 * @throws AuthenticationException In case of this service requires authentication and the current user session 85 * is not authenticated or doesn't have the right to access the service. 86 */ 87 @WebMethod 88 @WebResult(name = "category") 89 @RequiredRoles(ROLE_RUN_CATEGORIZATION_QUERIES) 90 Category getPlainCategory( 91 @WebParam(name = "locale") String locale, 92 @WebParam(name = "categoryName") String categoryName) throws AuthenticationException; 93 94 /** 95 * Returns all plain categories (without any view or child relationship). 96 * 97 * @param locale The locale (language & country) of the requester. 98 * @return All plain categories (without any view or child relationship). 99 * @throws AuthenticationException In case of this service requires authentication and the current user session 100 * is not authenticated or doesn't have the right to access the service. 101 */ 102 @WebMethod 103 @WebResult(name = "category") 104 @RequiredRoles(ROLE_RUN_CATEGORIZATION_QUERIES) 105 List<Category> getPlainCategories( 106 @WebParam(name = "locale") String locale) throws AuthenticationException; 107 108 /** 109 * Returns all declared, plain categories (without any view or child relationship and 110 * without any locale related filtering). 111 * <p/> 112 * Display names are returned using the ENGLISH locale. 113 * <p/> 114 * <b>Important Note:</b> There must not be 2 categories with the same name but different locale and different 115 * tag query expression. Only the display name may be non-unique. 116 * 117 * @return All declared categories. 118 * @throws AuthenticationException In case of this service requires authentication and the current user session 119 * is not authenticated or doesn't have the right to access the service. 120 */ 121 @WebMethod 122 @WebResult(name = "category") 123 @RequiredRoles(ROLE_RUN_CATEGORIZATION_QUERIES) 124 List<Category> getDeclaredCategories() throws AuthenticationException; 125 126 /** 127 * Is a shorthand for {@link FileService#getMatchingFiles(String, String, int)} 128 * used with the expressions returned from {@link #getPlainCategory(String, String)}. 129 * 130 * @param categoryName the category name identifying the category to return the referenced file for. 131 * @param pageNumber the page number to return. 132 * @return a identifier list page. 133 * @throws AuthenticationException In case of this service requires authentication and the current user session 134 * is not authenticated or doesn't have the right to access the service. 135 */ 136 @WebMethod 137 @WebResult(name = "fileId") 138 @RequiredRoles({ROLE_RUN_CATEGORIZATION_QUERIES, ROLE_RUN_TAG_MATCHING_QUERIES}) 139 FileIdentiferListPage getReferencedFiles( 140 @WebParam(name = "categoryName") String categoryName, 141 @WebParam(name = "pageNumber") int pageNumber) throws AuthenticationException; 142 143 /** 144 * Is a shorthand for {@link FileService#getMatchingFilesInRange(String, String, Range, int)} 145 * used with the expressions returned from {@link #getPlainCategory(String, String)}. 146 * 147 * @param categoryName the category name identifying the category to return the referenced file for. 148 * @param range the range used for filtering by date. 149 * @param pageNumber the page number to return. 150 * @return a identifier list page. 151 * @throws AuthenticationException In case of this service requires authentication and the current user session 152 * is not authenticated or doesn't have the right to access the service. 153 */ 154 @WebMethod 155 @WebResult(name = "fileId") 156 @RequiredRoles({ROLE_RUN_CATEGORIZATION_QUERIES, ROLE_RUN_TAG_MATCHING_QUERIES}) 157 FileIdentiferListPage getReferencedFilesInRange( 158 @WebParam(name = "categoryName") String categoryName, 159 @WebParam(name = "range") Range range, 160 @WebParam(name = "pageNumber") int pageNumber) throws AuthenticationException; 161 162 /** 163 * Is a shorthand for {@link PublicPackageService#getMatchingPackageNames(String, String, int)} 164 * used with the expressions returned from {@link #getPlainCategory(String, String)}. 165 * 166 * @param categoryName the category name identifying the category to return the referenced file for. 167 * @param pageNumber the page number to return. 168 * @return a identifier list page. 169 * @throws AuthenticationException In case of this service requires authentication and the current user session 170 * is not authenticated or doesn't have the right to access the service. 171 */ 172 @WebMethod 173 @WebResult(name = "fileId") 174 @RequiredRoles({ROLE_RUN_CATEGORIZATION_QUERIES, ROLE_RUN_TAG_MATCHING_QUERIES, ROLE_RUN_PACKAGE_QUERIES}) 175 NameListPage getReferencedPackageNames( 176 @WebParam(name = "categoryName") String categoryName, 177 @WebParam(name = "pageNumber") int pageNumber) throws AuthenticationException; 178 179 /** 180 * Is a shorthand for {@link PublicPackageService#getMatchingPackageNamesInRange(String, String, Range, int)} 181 * used with the expressions returned from {@link #getPlainCategory(String, String)}. 182 * 183 * @param categoryName the category name identifying the category to return the referenced file for. 184 * @param range the range used for filtering by date. 185 * @param pageNumber the page number to return. 186 * @return a identifier list page. 187 * @throws AuthenticationException In case of this service requires authentication and the current user session 188 * is not authenticated or doesn't have the right to access the service. 189 */ 190 @WebMethod 191 @WebResult(name = "fileId") 192 @RequiredRoles({ROLE_RUN_CATEGORIZATION_QUERIES, ROLE_RUN_TAG_MATCHING_QUERIES, ROLE_RUN_PACKAGE_QUERIES}) 193 NameListPage getReferencedPackageNamesInRange( 194 @WebParam(name = "categoryName") String categoryName, 195 @WebParam(name = "range") Range range, 196 @WebParam(name = "pageNumber") int pageNumber) throws AuthenticationException; 197 198 /** 199 * Returns the category names that reference this identifier. 200 * 201 * @param fileIdentifier the identifier to test against categorization. 202 * @return the category names that reference this identifier. 203 * @throws AuthenticationException In case of this service requires authentication and the current user session 204 * is not authenticated or doesn't have the right to access the service. 205 */ 206 @WebMethod 207 @WebResult(name = "names") 208 @RequiredRoles({ROLE_RUN_CATEGORIZATION_QUERIES, ROLE_RUN_COMPLEX_QUERIES}) 209 NameList getReferencingCategoryNamesOnFile( 210 @WebParam(name = "file") FileIdentifier fileIdentifier) throws AuthenticationException; 211 212 /** 213 * Returns the category names that reference these identifiers. 214 * 215 * @param fileIdentifiers the identifiers to test against categorization. 216 * @return the category names that reference these identifiers. 217 * @throws AuthenticationException In case of this service requires authentication and the current user session 218 * is not authenticated or doesn't have the right to access the service. 219 */ 220 @WebMethod 221 @WebResult(name = "names") 222 @RequiredRoles({ROLE_RUN_CATEGORIZATION_QUERIES, ROLE_RUN_COMPLEX_QUERIES}) 223 List<NameList> getReferencingCategoryNamesOnFiles( 224 @WebParam(name = "file") BatchCollection<FileIdentifier> fileIdentifiers) throws AuthenticationException; 225 226 /** 227 * Returns the category names that reference this package selected by its file identifier. 228 * 229 * @param fileIdentifier the identifier to test against categorization. 230 * @return the category names that reference this identifier. 231 * @throws AuthenticationException In case of this service requires authentication and the current user session 232 * is not authenticated or doesn't have the right to access the service. 233 */ 234 @WebMethod 235 @WebResult(name = "names") 236 @RequiredRoles({ROLE_RUN_CATEGORIZATION_QUERIES, ROLE_RUN_COMPLEX_QUERIES}) 237 NameList getReferencingCategoryNamesOnPackageById( 238 @WebParam(name = "packageFile") FileIdentifier fileIdentifier) throws AuthenticationException; 239 240 /** 241 * Returns the category names that reference these packages selected by their file identifiers. 242 * 243 * @param fileIdentifiers the identifiers to test against categorization. 244 * @return the category names that reference these identifiers. 245 * @throws AuthenticationException In case of this service requires authentication and the current user session 246 * is not authenticated or doesn't have the right to access the service. 247 */ 248 @WebMethod 249 @WebResult(name = "names") 250 @RequiredRoles({ROLE_RUN_CATEGORIZATION_QUERIES, ROLE_RUN_COMPLEX_QUERIES}) 251 List<NameList> getReferencingCategoryNamesOnPackagesById( 252 @WebParam(name = "packageFile") BatchCollection<FileIdentifier> fileIdentifiers) 253 throws AuthenticationException; 254 255 /** 256 * Returns the category names that reference this package selected by its name. 257 * 258 * @param packageName the name to test against categorization. 259 * @return the category names that reference this name. 260 * @throws AuthenticationException In case of this service requires authentication and the current user session 261 * is not authenticated or doesn't have the right to access the service. 262 */ 263 @WebMethod 264 @WebResult(name = "names") 265 @RequiredRoles({ROLE_RUN_CATEGORIZATION_QUERIES, ROLE_RUN_COMPLEX_QUERIES}) 266 NameList getReferencingCategoryNamesOnPackageByName( 267 @WebParam(name = "packageName") String packageName) throws AuthenticationException; 268 269 /** 270 * Returns the category names that reference these packages selected by their names. 271 * 272 * @param packageNames the names to test against categorization. 273 * @return the category names that reference these names. 274 * @throws AuthenticationException In case of this service requires authentication and the current user session 275 * is not authenticated or doesn't have the right to access the service. 276 */ 277 @WebMethod 278 @WebResult(name = "names") 279 @RequiredRoles({ROLE_RUN_CATEGORIZATION_QUERIES, ROLE_RUN_COMPLEX_QUERIES}) 280 List<NameList> getReferencingCategoryNamesOnPackagesByName( 281 @WebParam(name = "packageName") BatchCollection<String> packageNames) throws AuthenticationException; 282 283 /** 284 * Returns the category names that reference this file information list. 285 * 286 * @param informationList the information list to test against categorization. 287 * @return the category names that reference this list. 288 * @throws AuthenticationException In case of this service requires authentication and the current user session 289 * is not authenticated or doesn't have the right to access the service. 290 */ 291 @WebMethod 292 @WebResult(name = "names") 293 @RequiredRoles({ROLE_RUN_CATEGORIZATION_QUERIES, ROLE_RUN_COMPLEX_QUERIES}) 294 List<NameList> getReferencingCategoryNamesOnFileInformationList( 295 @WebParam(name = "information") BatchCollection<FileInformation> informationList) 296 throws AuthenticationException; 297 298 /** 299 * Returns the category names that reference this package information list. 300 * 301 * @param informationList the information list to test against categorization. 302 * @return the category names that reference this list. 303 * @throws AuthenticationException In case of this service requires authentication and the current user session 304 * is not authenticated or doesn't have the right to access the service. 305 */ 306 @WebMethod 307 @WebResult(name = "names") 308 @RequiredRoles({ROLE_RUN_CATEGORIZATION_QUERIES, ROLE_RUN_COMPLEX_QUERIES}) 309 List<NameList> getReferencingCategoryNamesOnPackageInformationList( 310 @WebParam(name = "information") BatchCollection<PackageInformation> informationList) 311 throws AuthenticationException; 312 }