1   package com.trendmicro.grid.acl.ds;
2   
3   import com.trendmicro.grid.acl.ds.datatypes.SharedSource;
4   import com.trendmicro.grid.acl.ds.datatypes.SharedSourceInformation;
5   import com.trendmicro.grid.acl.l0.datatypes.*;
6   import com.trendmicro.grid.acl.metadata.Metadata;
7   
8   import java.net.URI;
9   import java.util.Collection;
10  import java.util.Date;
11  
12  /**
13   * Defines a repository of sources for content stored inside the GRID.
14   *
15   * @author juergen_kellerer, 2010-05-07
16   * @version 1.0
17   */
18  public interface SourceRepository extends Repository {
19  
20  	/**
21  	 * Creates a plain identifier for the given URL.
22  	 * <p/>
23  	 * <b>Note:</b> This identifier may be used to query a source but there's no guarantee that
24  	 * the identifier returned by this method refers to an existing source. Therefore
25  	 * it cannot be used with methods that expect an identifier of a previously created
26  	 * source.
27  	 *
28  	 * @param remoteURI   The remote URL to create the identifier for.
29  	 * @param internalURI The internal URL to create the identifier for.
30  	 * @return A identifier for the given URL.
31  	 */
32  	SourceIdentifier createIdentifier(URI remoteURI, URI internalURI);
33  
34  	/**
35  	 * Returns all files that are referenced by the specified source.
36  	 *
37  	 * @param sourceIdentifier the identifier of the source to query.
38  	 * @param pageNumber       The number of the list page to return, starting from 0 for the first chunk.
39  	 * @return all files that are referenced by the specified source.
40  	 */
41  	FileIdentiferListPage getReferencedFiles(SourceIdentifier sourceIdentifier, int pageNumber);
42  
43  	/**
44  	 * Returns all package names that are referenced by the specified source.
45  	 *
46  	 * @param sourceIdentifier the identifier of the source to query.
47  	 * @param pageNumber       The number of the list page to return, starting from 0 for the first chunk.
48  	 * @return all package names that are referenced by the specified source.
49  	 */
50  	NameListPage getReferencedPackages(SourceIdentifier sourceIdentifier, int pageNumber);
51  
52  	/**
53  	 * Returns the source identifiers of all sources that are known for the given file.
54  	 * <p/>
55  	 * <b>Note:</b> Beginning with GACL 1.2, the returned sources are ordered by last modification
56  	 * date in descending order (newest comes first).
57  	 *
58  	 * @param file       The file to return the sources for.
59  	 * @param pageNumber The number of the list page to return, starting from 0 for the first chunk.
60  	 * @return A chunk of sources or 'null' if no chunk exists under the given number.
61  	 */
62  	SourceIdentiferListPage getReferencingSources(FileIdentifier file, int pageNumber);
63  
64  	/**
65  	 * Returns the source identifiers of all sources that belong to a certain domain and
66  	 * were last modified in a specifeid time range.
67  	 *
68  	 * @param domainName       The domain to return the sources for.
69  	 * @param modifiedFromDate The inclusive lower bound for the last-modified date value
70  	 *                         or 'null' if there is no lower bound.
71  	 * @param modifiedToDate   The exclusive upper bound for the last-modified date value
72  	 *                         or 'null' if there is no upper bound.
73  	 * @param pageNumber       The number of the list page to return, starting from 0 for the first chunk.
74  	 * @return A chunk of sources or 'null' if no chunk exists under the given number.
75  	 */
76  	SourceIdentiferListPage getSourcesOfDomainInRange(String domainName, Date modifiedFromDate, Date modifiedToDate, int pageNumber);
77  
78  	/**
79  	 * Returns the lightweight source-information list for the given source identifiers.
80  	 *
81  	 * @param identifiers The identifiers of the sources.
82  	 * @return The source-information list for the given identifiers or 'null' if a source does not yet exist.
83  	 */
84  	Collection<SharedSourceInformation> getSourceInformationList(Collection<SourceIdentifier> identifiers);
85  
86  	/**
87  	 * Returns the sources for the given source identifier.
88  	 *
89  	 * @param identifiers The identifiers of the sources.
90  	 * @return The sources for the given identifiers or 'null' if a source does not yet exist.
91  	 */
92  	Collection<SharedSource> getSources(Collection<SourceIdentifier> identifiers);
93  
94  	/**
95  	 * Creates the source with the given Metadata and returns the created source.
96  	 *
97  	 * @param remoteURI         The remote URI.
98  	 * @param internalURI       The internal URI.
99  	 * @param sourceInformation The source information of the source to create.
100 	 * @param metadata          The metadata to store with the source.
101 	 * @return the created source or 'null' if the source existed already.
102 	 */
103 	SharedSource createSource(URI remoteURI, URI internalURI, SourceInformation sourceInformation, Metadata metadata);
104 
105 	/**
106 	 * Updates the remote source with the given Metadata and returns the updated source.
107 	 *
108 	 * @param sourceInformation The source information of the source to update.
109 	 * @param metadata          The metadata to store with the source.
110 	 * @return the updated source or 'null' if the source did not exist.
111 	 */
112 	SharedSource updateSource(SourceInformation sourceInformation, Metadata metadata);
113 
114 	/**
115 	 * Sets the internal URI on a source with a non-null remote URI.
116 	 *
117 	 * @param identifier  The source to update set the internal URI for.
118 	 * @param internalURI The internal URI to set.
119 	 * @throws IllegalStateException In case of the source, idenfitied by the id does not define a remote URI.
120 	 */
121 	void setInternalURI(SourceIdentifier identifier, URI internalURI) throws IllegalStateException;
122 }