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
030 package org.hd.d.pg2k.ai.scorer;
031
032 import java.io.IOException;
033 import java.util.List;
034
035 import org.hd.d.pg2k.svrCore.Name;
036 import org.hd.d.pg2k.svrCore.datasource.SimpleExhibitPipelineIF;
037
038 /**
039 * Created by IntelliJ IDEA.
040 * User: DHD
041 * Date: 18-Apr-2006
042 * Time: 20:57:40
043 */
044
045 /**Base interface to compute the score and confidence for an exhibit.
046 * All methods in this interface are guaranteed to be "safe"
047 * insofaras they will complete in "reasonable" time
048 * with reasonable heap memory (and other resource, eg stack)
049 * and without doing anything that wouldn't be allowed in
050 * a minimal Applet/JWS sandbox.
051 * <p>
052 * All classes implementing this interface should be completely thread-safe
053 * in their implementation of the computeScoreAndConfidence() method,
054 * and preferrably purely functional (no visible side-effects),
055 * with as many concurrent threads as required safely doing separate computations
056 * in any one instance.
057 * <p>
058 * Classes implementing this interface should, where possible,
059 * do their calculations using integer arithmetic,
060 * since FPUs to support float/double calculations may be a scarce resource
061 * on newer highly-threaded CPUs such as Sun's Niagara
062 * and/or embedded CPUs such the ARMv5 in the SheevaPlug.
063 */
064 public interface ScorerIF
065 {
066 /**Compute score [-1,+1] and confidence[0,+1] for given exhibit; never null.
067 *
068 * @param dataSource source of exhibit data and metadata; never null
069 * @param exhibitName full name of exhibit; must be syntactically valid and not null
070 *
071 * @throws IOException in case of difficulty fetching the exhibit details/data
072 * or in computing the result
073 */
074 ScoreAndConf computeScoreAndConfidence(SimpleExhibitPipelineIF dataSource,
075 Name.ExhibitFull exhibitName)
076 throws IOException;
077
078 /**Get (base) name of this Scorer (excluding any parameters); never null.
079 * Pure alphanumeric, essentially the same rules as for a Java Class identifier
080 * (but with '$' and '_' and '.' excluded), ie <code>[a-zA-Z][a-zA-Z0-9]*</code>.
081 */
082 String getBaseName();
083
084 /**Get name of this Scorer suffixed with any parameters; never null.
085 * If there are any parameters then they appended with the form
086 * <code>(:name=value)*</code>.
087 */
088 String getNameAndParameters();
089
090 /**Computes randomly-perturbed parameters (if any); never null.
091 * This returns with zero or more of any parameters of the current Scorer
092 * usually altered by a small amount and guaranteed to be valid (in range).
093 * <p>
094 * The net effect is that most changes should be small and verging on insignificant,
095 * but some changes should be large enough to help escape from local minima/maxima.
096 */
097 List<ScorerParam> getPerturbedDefsAndValues();
098
099 /**Create perturbed (gently mutated) variant. */
100 ScorerIF createPerturbedVariant();
101
102 /**Get (immutable) canonical-order parameter definitions and current values for this Scorer; never null. */
103 List<ScorerParam> getParameterDefsAndValues();
104
105 /**Create variant of same base Scorer with (name and) parameters String; never null.
106 * Most Scorers will provide a public constructor taking a String argument with the same effect,
107 * but this allows us to enforce the requirement in the interface
108 * (at the low cost of retaining and starting from something like the no-arg instance).
109 * <p>
110 * May be able to share some (immutable) state with the original instance,
111 * and the value returned is immutable and may not be new.
112 *
113 * @throws IllegalArgumentException for unparsable or inappropriate input
114 */
115 ScorerIF createVariant(String nameAndParameters) throws IllegalArgumentException;
116
117 /**Create variant of same base Scorer with base name and parameters; never null.
118 * Most Scorers will provide a public constructor taking a String argument with the same effect,
119 * but this allows us to enforce the requirement in the interface
120 * (at the low cost of retaining and starting from something like the no-arg instance).
121 * <p>
122 * May be able to share some (immutable) state with the original instance,
123 * and the value returned is immutable and may not be new.
124 *
125 * @throws IllegalArgumentException for unparsable or inappropriate input
126 */
127 ScorerIF createVariant(String baseName, List<ScorerParam> parameters) throws IllegalArgumentException;
128 }