1 package com.trendmicro.grid.acl.l0; 2 3 import com.trendmicro.grid.acl.ProtectedRequestContext; 4 import com.trendmicro.grid.acl.RequiredRoles; 5 import com.trendmicro.grid.acl.Service; 6 import com.trendmicro.grid.acl.l0.datatypes.*; 7 import com.trendmicro.grid.acl.metadata.Metadata; 8 9 import javax.jws.WebMethod; 10 import javax.jws.WebParam; 11 import javax.jws.WebResult; 12 import javax.jws.WebService; 13 import javax.servlet.annotation.WebServlet; 14 import javax.xml.ws.ResponseWrapper; 15 import java.net.URI; 16 import java.util.Collection; 17 import java.util.Date; 18 19 import static com.trendmicro.grid.acl.l0.KnownRoles.*; 20 21 /** 22 * Defines TM reachable services to work with sources. 23 * 24 * @author Juergen_Kellerer, 2010-04-23 25 * @version 1.0 26 */ 27 @ProtectedRequestContext 28 @WebServlet("/ws/level-0/internal/sources") 29 @WebService(targetNamespace = Level0Constants.NAMESPACE) 30 public interface SourceService extends Service { 31 32 /** 33 * Returns the identifiers of all files that are referenced by the specified source. 34 * 35 * @param sourceIdentifier the identifier of the source to query. 36 * @param pageNumber The number of the list page to return, starting from 0 for the first chunk. 37 * @return the identifiers of all files that are referenced by the specified source or 'null' if no files are referenced. 38 * @throws AuthenticationException In case of the current user is not 39 * authenticated or doesn't have the right to access the service. 40 */ 41 @WebMethod 42 @WebResult(name = "fileIds") 43 @RequiredRoles({ROLE_ACCESS_PROTECTED_SERVICES, ROLE_RUN_COMPLEX_QUERIES}) 44 FileIdentiferListPage getFilesReferencedBySource( 45 @WebParam(name = "sourceIdentifier") SourceIdentifier sourceIdentifier, 46 @WebParam(name = "pageNumber") int pageNumber) throws AuthenticationException; 47 48 /** 49 * Returns all package names that are referenced by the specified source. 50 * 51 * @param sourceIdentifier the identifier of the source to query. 52 * @param pageNumber The number of the list page to return, starting from 0 for the first chunk. 53 * @return all package names that are referenced by the specified source or 'null' if no package names are referenced. 54 * @throws AuthenticationException In case of the current user is not 55 * authenticated or doesn't have the right to access the service. 56 */ 57 @WebMethod 58 @WebResult(name = "packageNames") 59 @RequiredRoles({ROLE_ACCESS_PROTECTED_SERVICES, ROLE_RUN_COMPLEX_QUERIES}) 60 NameListPage getPackagesReferencedBySource( 61 @WebParam(name = "sourceIdentifier") SourceIdentifier sourceIdentifier, 62 @WebParam(name = "pageNumber") int pageNumber) throws AuthenticationException; 63 64 /** 65 * Returns the source identifiers of all sources that are known for the given file. 66 * <p/> 67 * <b>Note:</b> Beginning with GACL 1.2, the returned sources are ordered by last modification 68 * date in descending order (newest comes first). 69 * 70 * @param file The file to return the sources for. 71 * @param pageNumber The number of the list page to return, starting from 0 for the first chunk. 72 * @return A chunk of sources or 'null' if no chunk exists under the given number. 73 * @throws AuthenticationException In case of the current user is not 74 * authenticated or doesn't have the right to access the service. 75 */ 76 @WebMethod 77 @WebResult(name = "sources") 78 @RequiredRoles({ROLE_ACCESS_PROTECTED_SERVICES, ROLE_RUN_COMPLEX_QUERIES}) 79 SourceIdentiferListPage getReferencingSources( 80 @WebParam(name = "file") FileIdentifier file, 81 @WebParam(name = "pageNumber") int pageNumber) throws AuthenticationException; 82 83 /** 84 * Creates a plain identifier for the given URL. 85 * <p/> 86 * <b>Note:</b> This identifier may be used to query a source but there's no guarantee that 87 * the identifier returned by this method refers to an existing source. Therefore 88 * it cannot be used with methods that expect an identifier of a previously created 89 * source. 90 * 91 * @param remoteSourceURL The remote URL to create the identifier for. 92 * @return A identifier for the given URL. 93 * @throws AuthenticationException In case of the current user is not 94 * authenticated or doesn't have the right to access the service. 95 */ 96 @WebMethod 97 @WebResult(name = "sourceIdentifier") 98 @RequiredRoles({ROLE_ACCESS_PROTECTED_SERVICES, ROLE_RUN_COMPLEX_QUERIES}) 99 SourceIdentifier createIdentifierForURL( 100 @WebParam(name = "remoteSourceURL") URI remoteSourceURL) throws AuthenticationException; 101 102 /** 103 * Returns the lightweight source-information for the given remote URL. 104 * 105 * @param remoteSourceURL the remote url to search the source for. 106 * @return The source-information for the given remote URL or 'null' if a source does not yet exist. 107 * @throws AuthenticationException In case of the current user is not 108 * authenticated or doesn't have the right to access the service. 109 */ 110 @WebMethod 111 @WebResult(name = "sourceInformation") 112 @RequiredRoles({ROLE_ACCESS_PROTECTED_SERVICES, ROLE_RUN_COMPLEX_QUERIES}) 113 SourceInformation getSourceInformationForURL( 114 @WebParam(name = "remoteSourceURL") URI remoteSourceURL) throws AuthenticationException; 115 116 /** 117 * Returns the lightweight source-information for the given source identifier. 118 * 119 * @param identifier The identifier of the source. 120 * @return The source-information for the given identifier or 'null' if a source does not yet exist. 121 * @throws AuthenticationException In case of the current user is not 122 * authenticated or doesn't have the right to access the service. 123 */ 124 @WebMethod 125 @WebResult(name = "sourceInformation") 126 @RequiredRoles({ROLE_ACCESS_PROTECTED_SERVICES, ROLE_RUN_COMPLEX_QUERIES}) 127 SourceInformation getSourceInformation( 128 @WebParam(name = "sourceIdentifier") SourceIdentifier identifier) throws AuthenticationException; 129 130 /** 131 * Returns the lightweight source-information list for the given source identifiers. 132 * 133 * @param identifiers The identifiers of the sources. 134 * @return The source-information list for the given identifiers or 'null' if a source does not yet exist. 135 * @throws AuthenticationException In case of the current user is not 136 * authenticated or doesn't have the right to access the service. 137 */ 138 @WebMethod 139 @WebResult(name = "sourceInformation") 140 @ResponseWrapper( // Adding a custom response wrapper to support 'null' values inside the returned collection. 141 className = "com.trendmicro.grid.acl.l0.wrappers.GetSourceInformationListResponse") 142 @RequiredRoles({ROLE_ACCESS_PROTECTED_SERVICES, ROLE_RUN_COMPLEX_QUERIES}) 143 Collection<SourceInformation> getSourceInformationList( 144 @WebParam(name = "sourceIdentifier") BatchCollection<SourceIdentifier> identifiers) 145 throws AuthenticationException; 146 147 /** 148 * Returns the source for the given remote URL. 149 * 150 * @param remoteSourceURL the remote url to search the source for. 151 * @return The source for the given remote URL or 'null' if a source does not yet exist. 152 * @throws AuthenticationException In case of the current user is not 153 * authenticated or doesn't have the right to access the service. 154 */ 155 @WebMethod 156 @WebResult(name = "source") 157 @RequiredRoles({ROLE_ACCESS_PROTECTED_SERVICES, ROLE_RUN_COMPLEX_QUERIES, ROLE_ACCESS_DETAILS}) 158 Source getSourceForURL( 159 @WebParam(name = "remoteSourceURL") URI remoteSourceURL) throws AuthenticationException; 160 161 /** 162 * Returns the source for the given source identifier. 163 * 164 * @param identifier The identifier of the source. 165 * @return The source for the given identifier or 'null' if a source does not yet exist. 166 * @throws AuthenticationException In case of the current user is not 167 * authenticated or doesn't have the right to access the service. 168 */ 169 @WebMethod 170 @WebResult(name = "source") 171 @RequiredRoles({ROLE_ACCESS_PROTECTED_SERVICES, ROLE_RUN_COMPLEX_QUERIES, ROLE_ACCESS_DETAILS}) 172 Source getSource( 173 @WebParam(name = "sourceIdentifier") SourceIdentifier identifier) throws AuthenticationException; 174 175 /** 176 * Returns the sources for the given source identifier. 177 * 178 * @param identifiers The identifiers of the sources. 179 * @return The sources for the given identifiers or 'null' if a source does not yet exist. 180 * @throws AuthenticationException In case of the current user is not 181 * authenticated or doesn't have the right to access the service. 182 */ 183 @WebMethod 184 @WebResult(name = "source") 185 @ResponseWrapper( // Adding a custom response wrapper to support 'null' values inside the returned collection. 186 className = "com.trendmicro.grid.acl.l0.wrappers.GetSourcesResponse") 187 @RequiredRoles({ROLE_ACCESS_PROTECTED_SERVICES, ROLE_RUN_COMPLEX_QUERIES, ROLE_ACCESS_DETAILS}) 188 Collection<Source> getSources( 189 @WebParam(name = "sourceIdentifier") BatchCollection<SourceIdentifier> identifiers) 190 throws AuthenticationException; 191 192 /** 193 * Creates a new remote source with the given values. 194 * 195 * @param remoteSourceURI The remote URI of the source. 196 * @param lastModified The remote last modified date of the source, if known (may be set to 'null'). 197 * @param contentTag The remote content tag (e.g. ETAG) of the source, if known (may be set to 'null'). 198 * @param metadata The metadata to store with the source. 199 * @return The identifier to the created source. 200 * @throws AuthenticationException In case of the current user is not 201 * authenticated or doesn't have the right to access the service. 202 * @throws IllegalRequestException In case of the URI exists already inside the CoreDB. 203 */ 204 @WebMethod 205 @WebResult(name = "sourceIdentifier") 206 @RequiredRoles({ROLE_ACCESS_PROTECTED_SERVICES, ROLE_PROCESS_CONTENT}) 207 SourceIdentifier createSource( 208 @WebParam(name = "remoteSourceURL") URI remoteSourceURI, 209 @WebParam(name = "lastModified") Date lastModified, 210 @WebParam(name = "contentTag") String contentTag, 211 @WebParam(name = "metadata") Metadata metadata) throws AuthenticationException, IllegalRequestException; 212 213 /** 214 * Creates a new internal temporary source with the given values. 215 * 216 * @param internalSourceURI The internal URI of the temporary source. 217 * @param lastModified The remote last modified date of the source, if known (may be set to 'null'). 218 * @param contentTag The remote content tag (e.g. ETAG) of the source, if known (may be set to 'null'). 219 * @param metadata The metadata to store with the source. 220 * @return The identifier to the created source. 221 * @throws AuthenticationException In case of the current user is not 222 * authenticated or doesn't have the right to access the service. 223 * @throws IllegalRequestException In case of the URI exists already inside the CoreDB. 224 */ 225 @WebMethod 226 @WebResult(name = "sourceIdentifier") 227 @RequiredRoles({ROLE_ACCESS_PROTECTED_SERVICES, ROLE_PROCESS_CONTENT}) 228 SourceIdentifier createTemporarySource( 229 @WebParam(name = "internalSourceURI") URI internalSourceURI, 230 @WebParam(name = "lastModified") Date lastModified, 231 @WebParam(name = "contentTag") String contentTag, 232 @WebParam(name = "metadata") Metadata metadata) throws AuthenticationException, IllegalRequestException; 233 234 /** 235 * Updates the source with the given Metadata without requiring to trigger a process. 236 * <p/> 237 * Note: This method will never create sources. No updates will be performed in case of the source 238 * information contains an invalid source identifier or if the source is not yet inside the database. 239 * 240 * @param sourceInformation The source information of the source to update. 241 * @param metadata The metadata to store with the source. 242 * @throws AuthenticationException In case of the current user is not 243 * authenticated or doesn't have the right to access the service. 244 * @throws IllegalRequestException In case of the source that is identified by the {@link SourceIdentifier}, 245 * doesn't exist inside the CoreDB. 246 */ 247 @WebMethod 248 @RequiredRoles({ROLE_ACCESS_PROTECTED_SERVICES, ROLE_PROCESS_CONTENT}) 249 void updateSource( 250 @WebParam(name = "sourceInformation") SourceInformation sourceInformation, 251 @WebParam(name = "metadata") Metadata metadata) throws AuthenticationException, IllegalRequestException; 252 253 /** 254 * Returns the source identifiers of all sources that belong to a certain domain. 255 * 256 * @param domainName The domain to return the sources for. 257 * @param pageNumber The number of the list page to return, starting from 0 for the first chunk. 258 * @return A chunk of sources or 'null' if no chunk exists under the given number. 259 * @throws AuthenticationException In case of the current user is not 260 * authenticated or doesn't have the right to access the service. 261 */ 262 @WebMethod 263 @WebResult(name = "sources") 264 @RequiredRoles({ROLE_ACCESS_PROTECTED_SERVICES, ROLE_RUN_COMPLEX_QUERIES}) 265 SourceIdentiferListPage getSourcesOfDomain( 266 @WebParam(name = "domainName") String domainName, 267 @WebParam(name = "pageNumber") int pageNumber) throws AuthenticationException; 268 269 /** 270 * Returns the source identifiers of all sources that belong to a certain domain and 271 * were last modified in a specifeid time range. 272 * <p/> 273 * Note: The result of this method is equvialent to the result of {@link #getSourcesOfDomain(String, int)})} 274 * in case of both date values are set to null inside the given range. 275 * 276 * @param domainName The domain to return the sources for. 277 * @param lastModifiedRange A DaysRange of type "LAST_MODIFIED". 278 * @param pageNumber The number of the list page to return, starting from 0 for the first chunk. 279 * @return A chunk of sources or 'null' if no chunk exists under the given number. 280 * @throws AuthenticationException In case of the current user is not 281 * authenticated or doesn't have the right to access the service. 282 */ 283 @WebMethod 284 @WebResult(name = "sources") 285 @RequiredRoles({ROLE_ACCESS_PROTECTED_SERVICES, ROLE_RUN_COMPLEX_QUERIES}) 286 SourceIdentiferListPage getSourcesOfDomainInRange( 287 @WebParam(name = "domainName") String domainName, 288 @WebParam(name = "lastModifiedRange") DaysRange lastModifiedRange, 289 @WebParam(name = "pageNumber") int pageNumber) throws AuthenticationException; 290 291 /** 292 * Returns the stored domain information on the given domain name. 293 * 294 * @param domainName the domain name to look for. 295 * @return the stored domain information on the given domain name. 296 * @throws AuthenticationException In case of the current user is not 297 * authenticated or doesn't have the right to access the service. 298 */ 299 @WebMethod 300 @WebResult(name = "sourceDomain") 301 @RequiredRoles({ROLE_ACCESS_PROTECTED_SERVICES, ROLE_RUN_COMPLEX_QUERIES, ROLE_ACCESS_DETAILS}) 302 SourceDomain getSourceDomain( 303 @WebParam(name = "domainName") String domainName) throws AuthenticationException; 304 305 /** 306 * Returns the a list of all stored domains. 307 * 308 * @param pageNumber The number of the list page to return, starting from 0 for the first chunk. 309 * @return A chunk of source domains or 'null' if no chunk exists under the given number. 310 * @throws AuthenticationException In case of the current user is not 311 * authenticated or doesn't have the right to access the service. 312 */ 313 @WebMethod 314 @WebResult(name = "sourceDomains") 315 @RequiredRoles({ROLE_ACCESS_PROTECTED_SERVICES, ROLE_RUN_COMPLEX_QUERIES, ROLE_ACCESS_DETAILS}) 316 SourceDomainListPage getSourceDomains( 317 @WebParam(name = "pageNumber") int pageNumber) throws AuthenticationException; 318 319 /** 320 * Returns the stored domain information on the given URL. 321 * 322 * @param sourceURL the url to lookup the domain of. 323 * @return the stored domain information on the given URL. 324 * @throws AuthenticationException In case of the current user is not 325 * authenticated or doesn't have the right to access the service. 326 */ 327 @WebMethod 328 @WebResult(name = "sourceDomain") 329 @RequiredRoles({ROLE_ACCESS_PROTECTED_SERVICES, ROLE_RUN_COMPLEX_QUERIES, ROLE_ACCESS_DETAILS}) 330 SourceDomain getSourceDomainForURL( 331 @WebParam(name = "sourceURL") URI sourceURL) throws AuthenticationException; 332 333 /** 334 * Updates the given domain information inside the persitence store. 335 * 336 * @param domain the domain info to update. 337 * @throws AuthenticationException In case of the current user is not 338 * authenticated or doesn't have the right to access the service. 339 */ 340 @WebMethod 341 @WebResult(name = "sourceDomain") 342 @RequiredRoles({ROLE_ACCESS_PROTECTED_SERVICES, ROLE_PROCESS_CONTENT}) 343 void updateSourceDomain( 344 @WebParam(name = "sourceDomain") SourceDomain domain) throws AuthenticationException; 345 }