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 package org.hd.d.pg2k.svrCore;
030
031 import java.io.IOException;
032
033 import org.hd.d.pg2k.svrCore.Name.ExhibitFull;
034 import org.hd.d.pg2k.svrCore.vars.BasicVarMgrInterface;
035
036
037 /**Interface for retrieving/calculating votes and correlations. */
038 public interface ExhibitPropsComputableMutableVoteCacheIF
039 {
040 /**Compute exactly one Factor that depends on explicit user votes for the specified exhibit; never null.
041 * Because voting is likely to be sparse,
042 * total up votes across all sample intervals to reduce noise,
043 * rather than taking each sample separately,
044 * and do various other calculations a little differently to dense measures.
045 * <p>
046 * If this cannot fetch some of the data it requires due to an IOException
047 * (not the same as fetching data successfully that has no entries)
048 * then the exception is propagated to the caller.
049 * (Normally this results in the EPCM item for which this is called
050 * being marked stale so that we can try again when the data is available.)
051 * <p>
052 * This may cache values once computed for efficiency.
053 * <p>
054 * The returned factor's goodness can range from -1 to +1,
055 * and confidence from 0 to +1;
056 * any scaling required will have to be applied elsewhere.
057 *
058 * @throws java.io.IOException if this was unable to fetch some data required
059 */
060 public ExhibitPropsComputableMutable.Factor calcVoteFactor(
061 final ExhibitFull exhibitName,
062 final AllExhibitProperties aep,
063 final BasicVarMgrInterface vars)
064 throws IOException;
065
066 /**Get correlates for specified exhibit; never null but result may be empty.
067 * This is based on votes of other "related" exhibits and exhibit metadata.
068 * <p>
069 * The goodness of each Factor is either -1 or +1,
070 * with the correlation/confidence ranging between 0 and 1.
071 * <p>
072 * This will return values computed up to one period ago if need be,
073 * to help avoid a sudden splurge of CPU effort as we tick from one period
074 * to the next.
075 * <p>
076 * No particular ordering of the results is guaranteed,
077 * but there will be no duplicates and no nulls.
078 *
079 * @param force if true, force complete computation if need be,
080 * else we will just return what we have in cache;
081 * complete recomputation may be expensive but should last a long time
082 * and we will abort with an IOException if we cannot complete
083 * the recomputation in a reasonable time
084 *
085 * @throws IOException cannot extract required correlates
086 */
087 public ExhibitPropsComputableMutable.Factor[] getCorrelates(
088 final ExhibitStaticAttr esa,
089 final AllExhibitProperties aep,
090 final BasicVarMgrInterface vars,
091 final boolean force)
092 throws IOException;
093
094 /**Find out if a category is rated "good"/popular or not.
095 * Returns TRUE if rated good, FALSE if bad,
096 * null if not significantly either or if not known.
097 *
098 * @param categoryDir the initial directory component of an extant exhibit
099 * @param force if true may force (expensive) computation to give
100 * a more accurate answer,
101 * else may return a more approximate or stale answer,
102 * or none at all (null)
103 */
104 public Boolean isCategoryGood(final CharSequence categoryDir,
105 final AllExhibitProperties aep,
106 final BasicVarMgrInterface vars,
107 final boolean force)
108 throws IOException;
109
110
111 /**Bring correlations data up to date.
112 * This may also perform housekeeping such as clearing stale state.
113 * <p>
114 * This may be a relatively expensive call.
115 * <p>
116 * This is thread-safe, though calling from more than one thread at once
117 * may result in redundant work being performed.
118 *
119 * @param aep current exhibit properties; never null
120 * @param vars handle on system variables; never null
121 * @param noTimeLimit if true, this runs until complete if possible
122 */
123 public void update(final AllExhibitProperties aep,
124 final BasicVarMgrInterface vars,
125 final boolean noTimeLimit)
126 throws IOException;
127
128
129
130
131 /**Trivial cache that doesn't actually cache anything, nor compute anything except the basic vote factor. */
132 public static final ExhibitPropsComputableMutableVoteCacheIF TRIVIAL =
133 new ExhibitPropsComputableMutableVoteCacheIF()
134 {
135 /**Fall through to directly compute the vote. */
136 public final ExhibitPropsComputableMutable.Factor calcVoteFactor(
137 final ExhibitFull exhibitName,
138 final AllExhibitProperties aep,
139 final BasicVarMgrInterface vars)
140 throws IOException
141 { return(ExhibitPropsComputableMutable.calcVoteFactor(exhibitName, aep, vars, 0)); }
142
143 /**Return empty correlates list. */
144 public ExhibitPropsComputableMutable.Factor[] getCorrelates(final ExhibitStaticAttr esa, final AllExhibitProperties aep, final BasicVarMgrInterface vars, final boolean force)
145 { return(new ExhibitPropsComputableMutable.Factor[0]); }
146
147 /**Do nothing. */
148 public void update(final AllExhibitProperties aep, final BasicVarMgrInterface vars, final boolean noTimeLimit)
149 { }
150
151 /**Find out if a category is rated "good"/popular or not; always returns null. */
152 public Boolean isCategoryGood(final CharSequence categoryDir, final AllExhibitProperties aep, final BasicVarMgrInterface vars, final boolean force)
153 { return(null); }
154 };
155 }