1 package com.trendmicro.grid.acl.ds;
2
3 import java.io.FileNotFoundException;
4 import java.io.IOException;
5 import java.io.InputStream;
6 import java.net.URI;
7 import java.security.DigestOutputStream;
8 import java.security.MessageDigest;
9 import java.util.Map;
10 import java.util.Date;
11
12 /**
13 * Defines an abstraction layer on top of a physical repository of files.
14 *
15 * @author juergen_kellerer, 2010-05-05
16 * @version 1.0
17 */
18 public interface FileContentRepository extends Repository {
19
20 /**
21 * Returns the name of the MessageDigest algorithm used for creating hashKeys.
22 *
23 * @return the name of the MessageDigest algorithm used for creating hashKeys.
24 */
25 String getHashKeyAlgorithm();
26
27 /**
28 * Returns a new instance of the MessageDigest used for creating hashKeys.
29 *
30 * @return a new instance of the MessageDigest used for creating hashKeys.
31 */
32 MessageDigest newHashKeyDigest();
33
34 /**
35 * Returns true if the file exists inside the underlying repository.
36 *
37 * @param hashKey the hash key identifying the file.
38 * @return true if the file exists inside the underlying repository.
39 */
40 boolean isExisting(byte[] hashKey);
41
42 /**
43 * Returns the time of the last modification.
44 *
45 * @param hashKey the hash key identifying the file.
46 * @return the time of the last modification or 'null' if the file doesn't exist.
47 */
48 Date getLastModified(byte[] hashKey);
49
50 /**
51 * Opens the specified file for writing.
52 * <p/>
53 * <b>Note:</b> The returned DigestOutputStream will compute the final hashKey during the write operation.
54 * {@code out.getMessageDigest().digest()} can be used to retrieve the final hashKey for a resource stored with
55 * a temporary key.
56 *
57 * @param hashKey the hash key identifying the file.
58 * @return a DigestOutputStream to write the content to.
59 * @throws FileNotFoundException if the file exists but is a directory rather than a regular file, does
60 * not exist but cannot be created, or cannot be opened for any other reason
61 * @throws IllegalStateException In case of the repository doesn't allow to write to the specified resource.
62 * May happen in write once repositories, when an attempt is made to overwrite
63 * a resource)
64 */
65 DigestOutputStream openForWrite(byte[] hashKey) throws FileNotFoundException, IllegalStateException;
66
67 /**
68 * Attaches the specified properites to the file identified by the hash.
69 *
70 * @param hashKey the hash key identifying the file.
71 * @param properties the properties to attach to the file.
72 * @throws IOException in case of attaching the properties failed.
73 */
74 void attachProperties(byte[] hashKey, Map<String, String> properties) throws IOException;
75
76 /**
77 * Returns true if the file exists inside the underlying repository.
78 *
79 * @param hashKey the hash key identifying the file.
80 * @return true if the file exists inside the underlying repository.
81 * @throws java.io.FileNotFoundException In case of the file, identified by the hashKey does not exist.
82 */
83 InputStream openForRead(byte[] hashKey) throws FileNotFoundException;
84
85 /**
86 * Reads previously attached properties.
87 *
88 * @param hashKey the hash key identifying the file.
89 * @return the properties attached to the file or 'null' if none were attached.
90 * @throws java.io.FileNotFoundException In case of the file, identified by the hashKey does not exist.
91 */
92 Map<String, String> readProperties(byte[] hashKey) throws IOException;
93
94 /**
95 * Renames the specified resource, if possible.
96 *
97 * @param fromHashKey The key identifying the resource to be renamed,
98 * @param toHashKey The new name of the resource.
99 * @throws IllegalArgumentException In case of a resource is renamed to a name that
100 * is considered invalid by the repository.
101 * @throws java.io.FileNotFoundException In case of the file,
102 * identified by the hashKey does not exist.
103 */
104 void rename(byte[] fromHashKey, byte[] toHashKey) throws FileNotFoundException, IllegalArgumentException;
105
106 /**
107 * Creates a temporary hash key for the given file.
108 *
109 * @return true if the file exists inside the underlying repository.
110 */
111 byte[] createTemporaryHashKey();
112
113 /**
114 * Encodes the hash key to a sharable network or machine internal URI.
115 *
116 * @param hashKey the hash key identifying the file.
117 * @return a sharable network or machine internal URI.
118 */
119 URI encodeToInternalURI(byte[] hashKey);
120
121 /**
122 * Decodes the hash key from a sharable network or machine internal URI.
123 *
124 * @param internalURI a sharable network or machine internal URI.
125 * @return the decoded hash key, or 'null' if the URI is not identifying a file inside the repository.
126 */
127 byte[] decodeFromInternalURI(URI internalURI);
128
129 /**
130 * Encodes the hash key to string.
131 *
132 * @param hashKey the hash key identifying the file.
133 * @return a string version of the hashkey.
134 */
135 String encodeHashKey(byte[] hashKey);
136
137 /**
138 * Decodes the hash key from string.
139 *
140 * @param hashKey the hash key string.
141 * @return the hash key.
142 */
143 byte[] decodeHashKey(String hashKey);
144 }