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