001 /**
002 * "TRMSim-WSN, Trust and Reputation Models Simulator for Wireless
003 * Sensor Networks" is free software: you can redistribute it and/or
004 * modify it under the terms of the GNU Lesser General Public License
005 * as published by the Free Software Foundation, either version 3 of
006 * the License, or (at your option) any later version always keeping
007 * the additional terms specified in this license.
008 *
009 * This program is distributed in the hope that it will be useful,
010 * but WITHOUT ANY WARRANTY; without even the implied warranty of
011 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
012 * GNU Lesser General Public License for more details.
013 *
014 *
015 * Additional Terms of this License
016 * --------------------------------
017 *
018 * 1. It is Required the preservation of specified reasonable legal notices
019 * and author attributions in that material and in the Appropriate Legal
020 * Notices displayed by works containing it.
021 *
022 * 2. It is limited the use for publicity purposes of names of licensors or
023 * authors of the material.
024 *
025 * 3. It is Required indemnification of licensors and authors of that material
026 * by anyone who conveys the material (or modified versions of it) with
027 * contractual assumptions of liability to the recipient, for any liability
028 * that these contractual assumptions directly impose on those licensors
029 * and authors.
030 *
031 * 4. It is Prohibited misrepresentation of the origin of that material, and it is
032 * required that modified versions of such material be marked in reasonable
033 * ways as different from the original version.
034 *
035 * 5. It is Declined to grant rights under trademark law for use of some trade
036 * names, trademarks, or service marks.
037 *
038 * You should have received a copy of the GNU Lesser General Public License
039 * along with this program (lgpl.txt). If not, see <http://www.gnu.org/licenses/>
040 */
041
042 package es.ants.felixgm.trmsim_wsn.trm;
043
044 import es.ants.felixgm.trmsim_wsn.outcomes.Outcome;
045 import es.ants.felixgm.trmsim_wsn.network.Sensor;
046 import es.ants.felixgm.trmsim_wsn.network.Network;
047 import es.ants.felixgm.trmsim_wsn.network.Service;
048
049 import java.util.Collection;
050 import java.util.Vector;
051
052 /**
053 * <p>This class represents a generic Trust and Reputation Model for Wireless Sensor Networks,
054 * also applicable to P2P and Ad-hoc ones</p>
055 <font color="#FF0000">
056 <p><strong>A subclass of this class has to be
057 implemented in order to add a new Trust and Reputation Model</strong></p>
058 </font>
059 * @author <a href="http://ants.dif.um.es/~felixgm/en" target="_blank">Félix Gómez Mármol</a>, <a href="http://webs.um.es/gregorio" target="_blank">Gregorio Martínez Pérez</a> and Antonio Bernárdez
060 * @version 0.2
061 */
062 public abstract class TRModel_WSN {
063 /** Trust and Reputation Model parameters */
064 protected TRMParameters trmParameters;
065
066 /**
067 * Creates a new instance of TRModel_WSN
068 * @param trmParameters Trust and Reputation Model parameters
069 */
070 protected TRModel_WSN(TRMParameters trmParameters) {
071 this.trmParameters = trmParameters;
072 }
073
074 /**
075 * This method collects or gathers the required information from the network needed
076 * to evaluate each sensor offering a given service in order to determine whether to
077 * have a transaction with it or not
078 * @param client The client applying this trust and reputation model in order to
079 * find the most trustworthy and reputable server offering a given service
080 * @param service The service requested by the given client
081 * @return The required information from the network needed to evaluate each
082 * sensor offering a given service in order to determine whether to have a
083 * transaction with it or not
084 */
085 public abstract GatheredInformation gatherInformation(Sensor client, Service service);
086
087 /**
088 * This method computes a trust and/or reputation value for each reachable server
089 * from the specified client and returns either a sorted list of all the reachable
090 * servers or a path leading directly to the most trustworthy and/or reputable one
091 * @param client The client applying this trust and reputation model in order to
092 * find the most trustworthy and reputable server offering a given service
093 * @param gi The gathered information fro the network needed in order to compute
094 * the trust and/or reputation value for each reachable server
095 * @return Either a path leading to the most trustworthy server found, or a
096 * sorted list of all the reachable servers
097 */
098 public abstract Vector<Sensor> scoreAndRanking(Sensor client, GatheredInformation gi);
099
100 /**
101 * This method actually requests a desired service to a specified server and
102 * evaluates the satisfaction of the client with the actually received service
103 * @param path Path of sensors leading to the most trustworthy and reputable server
104 * or sorted list of all the reachable servers
105 * @param service Service requested by the client running this trust and reputation model
106 * @return Outcome with the satisfaction of the client with the received service
107 */
108 public abstract Outcome performTransaction(Vector<Sensor> path, Service service);
109
110 /**
111 * This method rewards a server if the client is satisfied with the received
112 * service, according to that precise satisfaction
113 * @param path Path of sensors leading to the requesting server
114 * @param outcome Client's satisfaction with the received service
115 * @return Outcome with the updated transmitted distance of the messages sent
116 */
117 public abstract Outcome reward(Vector<Sensor> path, Outcome outcome);
118
119 /**
120 * This method punishes a server if the client is not satisfied with the received
121 * service, according to that precise dissatisfaction
122 * @param path Path of sensors leading to the requesting server
123 * @param outcome Client's dissatisfaction with the received service
124 * @return Outcome with the updated transmitted distance of the messages sent
125 */
126 public abstract Outcome punish(Vector<Sensor> path, Outcome outcome);
127
128 /**
129 * This method generates a new random network specific for this trust and
130 * reputation model
131 * @param numSensors Number of sensors composing the network
132 * @param probClients Probability of a sensor to act as a client requesting services
133 * @param rangeFactor Maximum wireless range of every sensor. It determines the neighborhood of every sensor
134 * @param probServices A collection of probabilities of offering a certain service, one per service
135 * @param probGoodness A collection of goodnesses about offering a certain service, one per service
136 * @param services All the services offered by the generated Network
137 * @return A new random network specific for this trust and reputation model
138 */
139 public abstract Network generateRandomNetwork(
140 int numSensors,
141 double probClients,
142 double rangeFactor,
143 Collection<Double> probServices,
144 Collection<Double> probGoodness,
145 Collection<Service> services);
146
147 /**
148 * This method loads a network from a XML file and creates the specific network
149 * corresponding to this trust and reputation model
150 * @param xmlFilePath Path of the XML to load the network from
151 * @return The loaded and generated specific network for this trust and
152 * reputation model
153 * @throws java.lang.Exception If the XML file given does not have the appropriate structure, or if
154 * a sensor links to an undefined sensor, or if a sensor links to itself
155 */
156 public abstract Network loadCurrentNetwork(String xmlFilePath) throws Exception;
157
158 /**
159 * Returns the associated trust and reputation model´s parameters
160 * @return The associated trust and reputation model´s parameters
161 */
162 public TRMParameters get_TRMParameters() { return trmParameters; }
163
164 /**
165 * Sets the associated trust and reputation model´s parameters
166 * @param trmParameters The associated trust and reputation model´s parameters
167 */
168 public void set_TRMParameters(TRMParameters trmParameters) { this.trmParameters = trmParameters; }
169 }