com.trendmicro.grid.acl.l0
Interface SourceService

All Superinterfaces:

Service

@ProtectedRequestContext
@WebServlet(value="/ws/level-0/internal/sources")
public interface SourceService
extends Service

Defines TM reachable services to work with sources.

Version:

1.0

Author:

Juergen_Kellerer, 2010-04-23

Method Summary

SourceIdentifier	createIdentifierForURL(URI remoteSourceURL) Creates a plain identifier for the given URL.
SourceIdentifier	createSource(URI remoteSourceURI, Date lastModified, String contentTag, com.trendmicro.grid.acl.metadata.Metadata metadata) Creates a new remote source with the given values.
SourceIdentifier	createTemporarySource(URI internalSourceURI, Date lastModified, String contentTag, com.trendmicro.grid.acl.metadata.Metadata metadata) Creates a new internal temporary source with the given values.
FileIdentiferListPage	getFilesReferencedBySource(SourceIdentifier sourceIdentifier, int pageNumber) Returns the identifiers of all files that are referenced by the specified source.
NameListPage	getPackagesReferencedBySource(SourceIdentifier sourceIdentifier, int pageNumber) Returns all package names that are referenced by the specified source.
SourceIdentiferListPage	getReferencingSources(FileIdentifier file, int pageNumber) Returns the source identifiers of all sources that are known for the given file.
Source	getSource(SourceIdentifier identifier) Returns the source for the given source identifier.
SourceDomain	getSourceDomain(String domainName) Returns the stored domain information on the given domain name.
SourceDomain	getSourceDomainForURL(URI sourceURL) Returns the stored domain information on the given URL.
SourceDomainListPage	getSourceDomains(int pageNumber) Returns the a list of all stored domains.
Source	getSourceForURL(URI remoteSourceURL) Returns the source for the given remote URL.
SourceInformation	getSourceInformation(SourceIdentifier identifier) Returns the lightweight source-information for the given source identifier.
SourceInformation	getSourceInformationForURL(URI remoteSourceURL) Returns the lightweight source-information for the given remote URL.
Collection<SourceInformation>	getSourceInformationList(BatchCollection<SourceIdentifier> identifiers) Returns the lightweight source-information list for the given source identifiers.
Collection<Source>	getSources(BatchCollection<SourceIdentifier> identifiers) Returns the sources for the given source identifier.
SourceIdentiferListPage	getSourcesOfDomain(String domainName, int pageNumber) Returns the source identifiers of all sources that belong to a certain domain.
SourceIdentiferListPage	getSourcesOfDomainInRange(String domainName, DaysRange lastModifiedRange, int pageNumber) Returns the source identifiers of all sources that belong to a certain domain and were last modified in a specifeid time range.
void	updateSource(SourceInformation sourceInformation, com.trendmicro.grid.acl.metadata.Metadata metadata) Updates the source with the given Metadata without requiring to trigger a process.
void	updateSourceDomain(SourceDomain domain) Updates the given domain information inside the persitence store.

Method Detail

getFilesReferencedBySource

@RequiredRoles(value={"access.protected.services","run.complex.queries"})
FileIdentiferListPage getFilesReferencedBySource(SourceIdentifier sourceIdentifier,
                                                                    int pageNumber)
                                                 throws AuthenticationException

Returns the identifiers of all files that are referenced by the specified source.

Parameters:

sourceIdentifier - the identifier of the source to query.

pageNumber - The number of the list page to return, starting from 0 for the first chunk.

Returns:

the identifiers of all files that are referenced by the specified source or 'null' if no files are referenced.

Throws:

AuthenticationException - In case of the current user is not authenticated or doesn't have the right to access the service.

getPackagesReferencedBySource

@RequiredRoles(value={"access.protected.services","run.complex.queries"})
NameListPage getPackagesReferencedBySource(SourceIdentifier sourceIdentifier,
                                                              int pageNumber)
                                           throws AuthenticationException

Returns all package names that are referenced by the specified source.

Parameters:

sourceIdentifier - the identifier of the source to query.

pageNumber - The number of the list page to return, starting from 0 for the first chunk.

Returns:

all package names that are referenced by the specified source or 'null' if no package names are referenced.

Throws:

AuthenticationException - In case of the current user is not authenticated or doesn't have the right to access the service.

getReferencingSources

@RequiredRoles(value={"access.protected.services","run.complex.queries"})
SourceIdentiferListPage getReferencingSources(FileIdentifier file,
                                                                 int pageNumber)
                                              throws AuthenticationException

Returns the source identifiers of all sources that are known for the given file.

Note: Beginning with GACL 1.2, the returned sources are ordered by last modification date in descending order (newest comes first).

Parameters:

file - The file to return the sources for.

pageNumber - The number of the list page to return, starting from 0 for the first chunk.

Returns:

A chunk of sources or 'null' if no chunk exists under the given number.

Throws:

AuthenticationException - In case of the current user is not authenticated or doesn't have the right to access the service.

createIdentifierForURL

@RequiredRoles(value={"access.protected.services","run.complex.queries"})
SourceIdentifier createIdentifierForURL(URI remoteSourceURL)
                                        throws AuthenticationException

Creates a plain identifier for the given URL.

Note: This identifier may be used to query a source but there's no guarantee that the identifier returned by this method refers to an existing source. Therefore it cannot be used with methods that expect an identifier of a previously created source.

Parameters:

remoteSourceURL - The remote URL to create the identifier for.

Returns:

A identifier for the given URL.

Throws:

AuthenticationException - In case of the current user is not authenticated or doesn't have the right to access the service.

getSourceInformationForURL

@RequiredRoles(value={"access.protected.services","run.complex.queries"})
SourceInformation getSourceInformationForURL(URI remoteSourceURL)
                                             throws AuthenticationException

Returns the lightweight source-information for the given remote URL.

Parameters:

remoteSourceURL - the remote url to search the source for.

Returns:

The source-information for the given remote URL or 'null' if a source does not yet exist.

Throws:

AuthenticationException - In case of the current user is not authenticated or doesn't have the right to access the service.

getSourceInformation

@RequiredRoles(value={"access.protected.services","run.complex.queries"})
SourceInformation getSourceInformation(SourceIdentifier identifier)
                                       throws AuthenticationException

Returns the lightweight source-information for the given source identifier.

Parameters:

identifier - The identifier of the source.

Returns:

The source-information for the given identifier or 'null' if a source does not yet exist.

Throws:

AuthenticationException - In case of the current user is not authenticated or doesn't have the right to access the service.

getSourceInformationList

@ResponseWrapper(className="com.trendmicro.grid.acl.l0.wrappers.GetSourceInformationListResponse")
@RequiredRoles(value={"access.protected.services","run.complex.queries"})
Collection<SourceInformation> getSourceInformationList(BatchCollection<SourceIdentifier> identifiers)
                                                       throws AuthenticationException

Returns the lightweight source-information list for the given source identifiers.

Parameters:

identifiers - The identifiers of the sources.

Returns:

The source-information list for the given identifiers or 'null' if a source does not yet exist.

Throws:

AuthenticationException - In case of the current user is not authenticated or doesn't have the right to access the service.

getSourceForURL

@RequiredRoles(value={"access.protected.services","run.complex.queries","access.details"})
Source getSourceForURL(URI remoteSourceURL)
                       throws AuthenticationException

Returns the source for the given remote URL.

Parameters:

remoteSourceURL - the remote url to search the source for.

Returns:

The source for the given remote URL or 'null' if a source does not yet exist.

Throws:

AuthenticationException - In case of the current user is not authenticated or doesn't have the right to access the service.

getSource

@RequiredRoles(value={"access.protected.services","run.complex.queries","access.details"})
Source getSource(SourceIdentifier identifier)
                 throws AuthenticationException

Returns the source for the given source identifier.

Parameters:

identifier - The identifier of the source.

Returns:

The source for the given identifier or 'null' if a source does not yet exist.

Throws:

AuthenticationException - In case of the current user is not authenticated or doesn't have the right to access the service.

getSources

@ResponseWrapper(className="com.trendmicro.grid.acl.l0.wrappers.GetSourcesResponse")
@RequiredRoles(value={"access.protected.services","run.complex.queries","access.details"})
Collection<Source> getSources(BatchCollection<SourceIdentifier> identifiers)
                              throws AuthenticationException

Returns the sources for the given source identifier.

Parameters:

identifiers - The identifiers of the sources.

Returns:

The sources for the given identifiers or 'null' if a source does not yet exist.

Throws:

AuthenticationException - In case of the current user is not authenticated or doesn't have the right to access the service.

createSource

@RequiredRoles(value={"access.protected.services","process.content"})
SourceIdentifier createSource(URI remoteSourceURI,
                                                 Date lastModified,
                                                 String contentTag,
                                                 com.trendmicro.grid.acl.metadata.Metadata metadata)
                              throws AuthenticationException,
                                     IllegalRequestException

Creates a new remote source with the given values.

Parameters:

remoteSourceURI - The remote URI of the source.

lastModified - The remote last modified date of the source, if known (may be set to 'null').

contentTag - The remote content tag (e.g. ETAG) of the source, if known (may be set to 'null').

metadata - The metadata to store with the source.

Returns:

The identifier to the created source.

Throws:

AuthenticationException - In case of the current user is not authenticated or doesn't have the right to access the service.

IllegalRequestException - In case of the URI exists already inside the CoreDB.

createTemporarySource

@RequiredRoles(value={"access.protected.services","process.content"})
SourceIdentifier createTemporarySource(URI internalSourceURI,
                                                          Date lastModified,
                                                          String contentTag,
                                                          com.trendmicro.grid.acl.metadata.Metadata metadata)
                                       throws AuthenticationException,
                                              IllegalRequestException

Creates a new internal temporary source with the given values.

Parameters:

internalSourceURI - The internal URI of the temporary source.

lastModified - The remote last modified date of the source, if known (may be set to 'null').

contentTag - The remote content tag (e.g. ETAG) of the source, if known (may be set to 'null').

metadata - The metadata to store with the source.

Returns:

The identifier to the created source.

Throws:

AuthenticationException - In case of the current user is not authenticated or doesn't have the right to access the service.

IllegalRequestException - In case of the URI exists already inside the CoreDB.

updateSource

@RequiredRoles(value={"access.protected.services","process.content"})
void updateSource(SourceInformation sourceInformation,
                                     com.trendmicro.grid.acl.metadata.Metadata metadata)
                  throws AuthenticationException,
                         IllegalRequestException

Updates the source with the given Metadata without requiring to trigger a process.

Note: This method will never create sources. No updates will be performed in case of the source information contains an invalid source identifier or if the source is not yet inside the database.

Parameters:

sourceInformation - The source information of the source to update.

metadata - The metadata to store with the source.

Throws:

AuthenticationException - In case of the current user is not authenticated or doesn't have the right to access the service.

IllegalRequestException - In case of the source that is identified by the SourceIdentifier, doesn't exist inside the CoreDB.

getSourcesOfDomain

@RequiredRoles(value={"access.protected.services","run.complex.queries"})
SourceIdentiferListPage getSourcesOfDomain(String domainName,
                                                              int pageNumber)
                                           throws AuthenticationException

Returns the source identifiers of all sources that belong to a certain domain.

Parameters:

domainName - The domain to return the sources for.

pageNumber - The number of the list page to return, starting from 0 for the first chunk.

Returns:

A chunk of sources or 'null' if no chunk exists under the given number.

Throws:

AuthenticationException - In case of the current user is not authenticated or doesn't have the right to access the service.

getSourcesOfDomainInRange

@RequiredRoles(value={"access.protected.services","run.complex.queries"})
SourceIdentiferListPage getSourcesOfDomainInRange(String domainName,
                                                                     DaysRange lastModifiedRange,
                                                                     int pageNumber)
                                                  throws AuthenticationException

Returns the source identifiers of all sources that belong to a certain domain and were last modified in a specifeid time range.

Note: The result of this method is equvialent to the result of getSourcesOfDomain(String, int))} in case of both date values are set to null inside the given range.

Parameters:

domainName - The domain to return the sources for.

lastModifiedRange - A DaysRange of type "LAST_MODIFIED".

pageNumber - The number of the list page to return, starting from 0 for the first chunk.

Returns:

A chunk of sources or 'null' if no chunk exists under the given number.

Throws:

AuthenticationException - In case of the current user is not authenticated or doesn't have the right to access the service.

getSourceDomain

@RequiredRoles(value={"access.protected.services","run.complex.queries","access.details"})
SourceDomain getSourceDomain(String domainName)
                             throws AuthenticationException

Returns the stored domain information on the given domain name.

Parameters:

domainName - the domain name to look for.

Returns:

the stored domain information on the given domain name.

Throws:

AuthenticationException - In case of the current user is not authenticated or doesn't have the right to access the service.

getSourceDomains

@RequiredRoles(value={"access.protected.services","run.complex.queries","access.details"})
SourceDomainListPage getSourceDomains(int pageNumber)
                                      throws AuthenticationException

Returns the a list of all stored domains.

Parameters:

pageNumber - The number of the list page to return, starting from 0 for the first chunk.

Returns:

A chunk of source domains or 'null' if no chunk exists under the given number.

Throws:

AuthenticationException - In case of the current user is not authenticated or doesn't have the right to access the service.

getSourceDomainForURL

@RequiredRoles(value={"access.protected.services","run.complex.queries","access.details"})
SourceDomain getSourceDomainForURL(URI sourceURL)
                                   throws AuthenticationException

Returns the stored domain information on the given URL.

Parameters:

sourceURL - the url to lookup the domain of.

Returns:

the stored domain information on the given URL.

Throws:

AuthenticationException - In case of the current user is not authenticated or doesn't have the right to access the service.

updateSourceDomain

@RequiredRoles(value={"access.protected.services","process.content"})
void updateSourceDomain(SourceDomain domain)
                        throws AuthenticationException

Updates the given domain information inside the persitence store.

Parameters:

domain - the domain info to update.

Throws:

AuthenticationException - In case of the current user is not authenticated or doesn't have the right to access the service.