001 /*
002 Copyright (c) 1996-2012, 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
030 package org.hd.d.pg2k.webSvr.threeD;
031
032 import java.io.IOException;
033 import java.util.StringTokenizer;
034
035 import org.hd.d.pg2k.svrCore.Name;
036 import org.hd.d.pg2k.svrCore.Name.ExhibitFull;
037
038 /**
039 * Created by IntelliJ IDEA.
040 * User: DHD
041 * Date: 11-Mar-2006
042 * Time: 13:22:06
043 */
044
045 /**This interface is used for light-weight, incremental fetching of Gallery metadata, eg for an interactive 3D walkthrough.
046 */
047 interface LightweightMetaDataFetchInterface
048 {
049 /**Immutable store of the most basic Gallery meta-data.
050 * This contains a hash over the Gallery contents
051 * that should change whenever the set of exhibits in the Gallery changes,
052 * and a (non-negative) count of exhibits in the Gallery.
053 * <p>
054 * This also contains an expected maximum validity period
055 * for this and related mata-data fetched through this interface,
056 * ie within what short of time it should be revalidated or discarded.
057 */
058 public static final class GalleryBasicMetaData
059 {
060 /**Hash over exhibit set. */
061 public final long exhibitSetHash;
062
063 /**Count of exhibits in the Gallery; non-negative. */
064 public final int exhibitCount;
065
066 /**Validity period (maximum cache time) in milliseconds; non-negative. */
067 public final int metaDataMaxCacheLifeMs;
068
069 /**Create an instance.
070 * The exhibit count and cache time must be non-negative.
071 */
072 public GalleryBasicMetaData(final long hash,
073 final int count,
074 final int cacheMs)
075 {
076 exhibitSetHash = hash;
077 exhibitCount = count;
078 metaDataMaxCacheLifeMs = cacheMs;
079
080 if(exhibitCount < 0) { throw new IllegalArgumentException(); }
081 if(metaDataMaxCacheLifeMs < 0) { throw new IllegalArgumentException(); }
082 }
083
084 /**Create an instance parsed from on-the-wire format; never null.
085 * @param s value as generated by toWireString(); never null
086 * @return instance; never null
087 * @throws IllegalArgumentException if input String is invalid
088 */
089 public static GalleryBasicMetaData fromWireString(final String s)
090 throws IllegalArgumentException
091 {
092 final StringTokenizer st = new StringTokenizer(s, ":");
093 final long hash = Long.parseLong(st.nextToken(), 10);
094 final int count = Integer.parseInt(st.nextToken(), 10);
095 final int cacheTime = Integer.parseInt(st.nextToken(), 10);
096 return(new GalleryBasicMetaData(hash, count, cacheTime));
097 }
098
099 /**Convert to String for suitable to use on the wire; pure printable ASCII. */
100 public String toWireString()
101 {
102 final StringBuilder sb = new StringBuilder(64);
103 sb.append(exhibitSetHash).
104 append(':').append(exhibitCount).
105 append(':').append(metaDataMaxCacheLifeMs);
106 return(sb.toString());
107 }
108
109 /**Human-readable string format. */
110 @Override
111 public String toString() { return(toWireString()); }
112
113 /**Default/empty instance. */
114 public static final GalleryBasicMetaData EMPTY = new GalleryBasicMetaData(0, 0, 0);
115 }
116
117 /**Fetch the current exhibit-set hash and exhibit count; never null.
118 * A change in the hash is a signal that cached data may be invalid
119 * and need to be purged or revalidated.
120 */
121 public GalleryBasicMetaData getGalleryBasicMetaData() throws IOException;
122
123 /**Fetch the full name of the given numbered exhibit; null if no such exhibit or not currently available.
124 * The range is 0 to numberOfExhibits-1.
125 * <p>
126 * This assumes that there is a sensible stable ordering of exhibits,
127 * probably in "smart-sorted" order or similar.
128 * <p>
129 * This ordering is fixed from one exhibit set to the next,
130 * ie is stable while the exhibit set hash remains unchanged.
131 */
132 public ExhibitFull getExhibitName(final int ordinal);
133
134 /**Maximum number of names that can be requested at once with getExhibitNames(); strictly positive.
135 * High enough to help overcome network latency,
136 * but not large enough to take significant CPU time or response size.
137 */
138 public static final int MAX_NAMES_REQUEST = 32;
139
140 /**Fetch the full name of the given numbered exhibits; each entry null if no such exhibit or not currently available, overall result never null.
141 * The range for each item is 0 to numberOfExhibits-1.
142 * <p>
143 * This assumes that there is a sensible stable ordering of exhibits,
144 * probably in "smart-sorted" order or similar.
145 * <p>
146 * This ordering is fixed from one exhibit set to the next,
147 * ie is stable while the exhibit set hash remains unchanged.
148 */
149 public Name.ExhibitFull[] getExhibitNames(final int ordinals[]);
150 }