001 /*
002 Copyright (c) 1996-2009, Damon Hart-Davis
003 All rights reserved.
004
005 Redistribution and use in source and binary forms, with or without
006 modification, are permitted provided that the following conditions are
007 met:
008
009 * Redistributions of source code must retain the above copyright
010 notice, this list of conditions and the following disclaimer.
011
012 * Redistributions in binary form must reproduce the above copyright
013 notice, this list of conditions and the following disclaimer in the
014 documentation and/or other materials provided with the
015 distribution.
016
017 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
018 IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
019 TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
020 PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
021 OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
022 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
023 LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
024 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
025 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
026 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
027 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
028 */
029 package org.hd.d.pg2k.svrCore.datasource;
030
031 import java.io.IOException;
032 import java.nio.ByteBuffer;
033
034 import org.hd.d.pg2k.svrCore.AllExhibitImmutableData;
035 import org.hd.d.pg2k.svrCore.AllExhibitProperties;
036 import org.hd.d.pg2k.svrCore.ExhibitStaticAttr;
037 import org.hd.d.pg2k.svrCore.ExhibitThumbnails;
038 import org.hd.d.pg2k.svrCore.Name;
039 import org.hd.d.pg2k.svrCore.Name.ExhibitFull;
040 import org.hd.d.pg2k.svrCore.props.GenProps;
041 import org.hd.d.pg2k.svrCore.vars.SimpleVariablePipelineIF;
042
043 /**Simple interface implemented by several stages in the Web exhibit-handling pipeline.
044 * In particular, the on-disc exhibit-data cache and backend datasource adaptors
045 * implement this.
046 * <p>
047 * The pipeline stages that implement this may well implement other interfaces
048 * in parallel to provide richer and more efficient cacheing, etc.
049 * <p>
050 * As this is in effect handling a stream of I/O on its way to a browser,
051 * IOException seems the natural way to signal errors.
052 * <p>
053 * We may make implementers of this interface Serializable so as to allow
054 * them to be persisted
055 * in servlet context for robustness and distribution, but making
056 * copies through this mechanism will upset the ability to fully track
057 * usage and efficiently share caches, etc.
058 * <p>
059 * Note that this extends the variable-handling pipeline interface,
060 * ie data pipelines also handle system variables.
061 */
062 public interface SimpleExhibitPipelineIF extends SimpleVariablePipelineIF
063 {
064 /**Maximum exhibit user-driven I/O data transfer request in bytes; strictly positive.
065 * This is the limit for filesystem access, tunnel connections, etc,
066 * to avoid causing bottlenecks and out-of-memory conditions.
067 * <p>
068 * Some operations that request transfers larger than this
069 * (and where the caller has control of the size of the request),
070 * eg reading raw data from an exhibit,
071 * may be rejected with an IOException.
072 * <p>
073 * Note that this does not limit the return of large data items
074 * (eg AllExhibitProperties) whose size is not controlled by the caller.
075 * <p>
076 * This helps prevent denial-of-service by a faulty/malicious client.
077 * <p>
078 * A power of two for efficiency in various places.
079 * <p>
080 * A size of many times BULK_DATA_TRANSFER_SIZE to a few mBytes
081 * is probably reasonable.
082 */
083 public static final int MAX_USER_READ_SIZE = 1 * 1024 * 1024;
084
085 /**Get the static attributes for a given exhibit.
086 * Returns null if the named exhibit does not exist.
087 *
088 * @throws java.io.IOException if the operation cannot be completed due to I/O
089 * restrictions or failure
090 */
091 public ExhibitStaticAttr getStaticAttr(ExhibitFull name)
092 throws IOException;
093
094 /**Read a chunk of the raw exhibit binary into the given buffer.
095 * The call may return less than the the buffer capacity,
096 * though will block until it has read at least one byte unless at EOF or for a zero-byte request;
097 * this will be clear from the state of the buffer.
098 *
099 * @param buf the buffer into which to read the data;
100 * must be non-null, in put()able state,
101 * and with remaining capacity of at least the requested number of bytes
102 * @param exhibitName the full name of the exhibit to read from;
103 * never null and must be syntactically valid
104 * @param position position/index of first byte in exhibitFile to read;
105 * non-negative
106 * @param dontCache if true, this is a hint not to attempt to cache this
107 * or displace anything from extant caches for this data
108 * as it may for example be precaching or random activity;
109 * by default callers should leave this false to allow cacheing
110 *
111 * @throws java.lang.IllegalArgumentException for invalid arguments such as
112 * a null or syntactically-invalid name,
113 * a negative position or excessive number of requested bytes,
114 * a negative (or in some cases, non-positive) len
115 * @throws java.io.IOException for requests that cannot be fulfilled because of
116 * I/O restrictions or problems, such as link failure or
117 * an upper bound on the length of a request
118 */
119 public void getRawFile(ByteBuffer buf,
120 Name.ExhibitFull exhibitName, int position, boolean dontCache)
121 throws IOException;
122
123 /**Gets set of all static exhibit data if its timestamp is not that specified.
124 * If the time specified is negative the object will be returned unconditionally.
125 * <p>
126 * If no exhibits are currently installed a default set with a zero
127 * timestamp is returned.
128 * <p>
129 * If the caller's copy appears to be up-to-date (eg the oldStamp
130 * matches that that would have been returned) null is returned.
131 *
132 * @throws java.io.IOException if the operation cannot be completed due to I/O
133 * restrictions or failure
134 */
135 public AllExhibitImmutableData getAllExhibitImmutableData(long oldStamp)
136 throws IOException;
137
138 /**Gets set of all exhibit properties if its hash is not that specified; never null for -1 argument.
139 * If the hash specified is negative the object will be returned unconditionally.
140 * <p>
141 * If no exhibits are currently installed a default set with a zero
142 * timestamp is returned.
143 * <p>
144 * If the caller's copy appears to be up-to-date (eg the oldHash
145 * matches that that would have been returned) null is returned.
146 *
147 * @throws java.io.IOException if the operation cannot be completed due to I/O
148 * restrictions or failure
149 */
150 public AllExhibitProperties getAllExhibitProperties(long oldHash)
151 throws IOException;
152
153 /**Gets the general properties as a GenProps object if its timestamp is not that specified; never null for -1 argument.
154 * If the time specified is negative the object will be returned unconditionally.
155 * <p>
156 * If no props are currently installed/available a default set with a zero
157 * timestamp is returned.
158 * <p>
159 * If the caller's copy appears to be up-to-date (eg the oldStamp
160 * matches that that would have been returned) null is returned.
161 *
162 * @throws java.io.IOException if the operation cannot be completed due to I/O
163 * restrictions or failure
164 */
165 public org.hd.d.pg2k.svrCore.props.GenProps getGenProps(long oldStamp)
166 throws IOException;
167
168 /**Gets the generic security properties as a Properties object if its timestamp is not that specified.
169 * If the time specified is negative the object will be returned unconditionally.
170 * <p>
171 * If no props are currently installed/available a default set with a zero
172 * timestamp is returned.
173 * <p>
174 * If the caller's copy appears to be up-to-date (eg the oldStamp
175 * matches that that would have been returned) null is returned.
176 *
177 * @deprecated Use getProperties() for new code.
178 *
179 * @throws java.io.IOException if the operation cannot be completed due to I/O
180 * restrictions or failure
181 */
182 @Deprecated
183 public java.util.Properties getGenSecProps(long oldStamp)
184 throws IOException;
185
186 /**Gets the thumbnails for an exhibit.
187 * A data source is at liberty to refuse to compute thumbnails
188 * in which case it may return null, else it returns a
189 * non-null value which may include the `could-not-compute'
190 * value to indicate that a thumbnail/sample cannot be made
191 * for this exhibit and no attempt need be made in future.
192 *
193 * @param create if true, and no thumbnail yet exists, try to
194 * create one if possible, else if create is false
195 * only return an existing one and return null if none is to hand
196 *
197 * @throws java.io.IOException if the operation cannot be completed due to I/O
198 * restrictions or failure
199 */
200 public ExhibitThumbnails getThumbnails(ExhibitFull name, boolean create)
201 throws IOException;
202
203 /**Class that holds key to Properties lookup/fetch.
204 * Immutable, and can be used as a key in a hash table.
205 */
206 public enum PropsKey
207 {
208 /**Generic security properties. */
209 GenSecProps,
210
211 /**Properties map from IPv4 octet prefix to ccTLD/region. */
212 IPToCCTld,
213
214 /**Location map from exhibit name (usually prefix/suffix) to Location value. */
215 NameToLocation,
216 }
217
218 /**Get requested Properties selected by key and versionID.
219 * Fetches a Properties set unconditionally (versionID == -1)
220 * else if the versionID presented is not current.
221 *
222 * @param key selector (with possible embedded sub-key)
223 * for desired properties set; never null
224 * @param versionID if -1 then map is always returned if available,
225 * else must be non-negative and null is returned if the versionID
226 * presented matches that of the current version
227 * (ie if the caller has presumably got the up-to-date version);
228 * may be a timestamp or a hash or other value,
229 * and by convention is zero only for an empty properties set
230 *
231 * @return null, or Properties map guaranteed to contain only
232 * String keys and values
233 */
234 public java.util.Properties getProperties(PropsKey key, long versionID)
235 throws IOException;
236
237
238 /**Poll periodically (of the order of seconds) to do background work.
239 * The current generic system properties are passed in...
240 * <p>
241 * @throws java.io.IOException in case of difficulty, but even if a sub-ordinate
242 * call throws IOException then poll() call should continue
243 * to do as much of its remaining work as reasonably possible
244 */
245 public void poll(GenProps gp)
246 throws IOException;
247
248 /**Shut down the data pipeline.
249 * Free resources having saved any persistent state
250 * and shut down any upstream components.
251 */
252 public void destroy();
253 }