1 /* Copyright (C) 2004 - 2009 Versant Inc. http://www.db4o.com */ 2 3 using Db4objects.Db4o.Query; 4 5 namespace Db4objects.Db4o.Query 6 { 7 /// <summary> 8 /// constraint to limit the objects returned upon 9 /// <see cref="Db4objects.Db4o.Query.IQuery.Execute">query execution</see> 10 /// . 11 /// <br/><br/> 12 /// Constraints are constructed by calling 13 /// <see cref="Db4objects.Db4o.Query.IQuery.Constrain">Db4objects.Db4o.Query.IQuery.Constrain 14 /// </see> 15 /// . 16 /// <br/><br/> 17 /// Constraints can be joined with the methods 18 /// <see cref="Db4objects.Db4o.Query.IConstraint.And">Db4objects.Db4o.Query.IConstraint.And 19 /// </see> 20 /// and 21 /// <see cref="Db4objects.Db4o.Query.IConstraint.Or">Db4objects.Db4o.Query.IConstraint.Or 22 /// </see> 23 /// . 24 /// <br/><br/> 25 /// The methods to modify the constraint evaluation algorithm may 26 /// be merged, to construct combined evaluation rules. 27 /// Examples: 28 /// <ul> 29 /// <li> <code>Constraint.Smaller().Equal()</code> for "smaller or equal" </li> 30 /// <li> <code>Constraint.Not().Like()</code> for "not like" </li> 31 /// <li> <code>Constraint.Not().Greater().Equal()</code> for "not greater or equal" </li> 32 /// </ul> 33 /// </summary> 34 public interface IConstraint 35 { 36 /// <summary>links two Constraints for AND evaluation.</summary> 37 /// <remarks> 38 /// links two Constraints for AND evaluation. 39 /// For example:<br/> 40 /// <code>query.Constrain(typeof(Pilot));</code><br/> 41 /// <code>query.Descend("points").Constrain(101).Smaller().And(query.Descend("name").Constrain("Test Pilot0")); </code><br/> 42 /// will retrieve all pilots with points less than 101 and name as "Test Pilot0"<br/> 43 /// </remarks> 44 /// <param name="with"> 45 /// the other 46 /// <see cref="Db4objects.Db4o.Query.IConstraint">Db4objects.Db4o.Query.IConstraint</see> 47 /// </param> 48 /// <returns> 49 /// a new 50 /// <see cref="Db4objects.Db4o.Query.IConstraint">Db4objects.Db4o.Query.IConstraint</see> 51 /// , that can be used for further calls 52 /// to 53 /// <see cref="Db4objects.Db4o.Query.IConstraint.And">And</see> 54 /// and 55 /// <see cref="Db4objects.Db4o.Query.IConstraint.Or">Or</see> 56 /// </returns> And(IConstraint with)57 IConstraint And(IConstraint with); 58 59 /// <summary>links two Constraints for OR evaluation.</summary> 60 /// <remarks> 61 /// links two Constraints for OR evaluation. 62 /// For example:<br/><br/> 63 /// <code>query.Constrain(typeof(Pilot));</code><br/> 64 /// <code>query.Descend("points").Constrain(101).Greater().Or(query.Descend("name").Constrain("Test Pilot0"));</code><br/> 65 /// will retrieve all pilots with points more than 101 or pilots with the name "Test Pilot0"<br/> 66 /// </remarks> 67 /// <param name="with"> 68 /// the other 69 /// <see cref="Db4objects.Db4o.Query.IConstraint">Db4objects.Db4o.Query.IConstraint</see> 70 /// </param> 71 /// <returns> 72 /// a new 73 /// <see cref="Db4objects.Db4o.Query.IConstraint">Db4objects.Db4o.Query.IConstraint</see> 74 /// , that can be used for further calls 75 /// to 76 /// <see cref="Db4objects.Db4o.Query.IConstraint.And">And</see> 77 /// and 78 /// <see cref="Db4objects.Db4o.Query.IConstraint.Or">Or</see> 79 /// </returns> Or(IConstraint with)80 IConstraint Or(IConstraint with); 81 82 /// <summary> 83 /// Used in conjunction with 84 /// <see cref="Db4objects.Db4o.Query.IConstraint.Smaller">Db4objects.Db4o.Query.IConstraint.Smaller 85 /// </see> 86 /// or 87 /// <see cref="Db4objects.Db4o.Query.IConstraint.Greater">Db4objects.Db4o.Query.IConstraint.Greater 88 /// </see> 89 /// to create constraints 90 /// like "smaller or equal", "greater or equal". 91 /// For example:<br/> 92 /// <code>query.Constrain(typeof(Pilot));</code><br/> 93 /// <code>query.Descend("points").Constrain(101).Smaller().Equal();</code><br/> 94 /// will return all pilots with points <= 101.<br/> 95 /// </summary> 96 /// <returns> 97 /// this 98 /// <see cref="Db4objects.Db4o.Query.IConstraint">Db4objects.Db4o.Query.IConstraint</see> 99 /// to allow the chaining of method calls. 100 /// </returns> Equal()101 IConstraint Equal(); 102 103 /// <summary>sets the evaluation mode to <code>></code>.</summary> 104 /// <remarks> 105 /// sets the evaluation mode to <code>></code>. 106 /// For example:<br/> 107 /// <code>query.Constrain(typeof(Pilot));</code><br/> 108 /// <code>query.Descend("points").Constrain(101).Greater()</code><br/> 109 /// will return all pilots with points > 101.<br/> 110 /// </remarks> 111 /// <returns> 112 /// this 113 /// <see cref="Db4objects.Db4o.Query.IConstraint">Db4objects.Db4o.Query.IConstraint</see> 114 /// to allow the chaining of method calls. 115 /// </returns> Greater()116 IConstraint Greater(); 117 118 /// <summary>sets the evaluation mode to <code><</code>.</summary> 119 /// <remarks> 120 /// sets the evaluation mode to <code><</code>. 121 /// For example:<br/> 122 /// <code>query.Constrain(typeof(Pilot));</code><br/> 123 /// <code>query.Descend("points").Constrain(101).Smaller()</code><br/> 124 /// will return all pilots with points < 101.<br/> 125 /// </remarks> 126 /// <returns> 127 /// this 128 /// <see cref="Db4objects.Db4o.Query.IConstraint">Db4objects.Db4o.Query.IConstraint</see> 129 /// to allow the chaining of method calls. 130 /// </returns> Smaller()131 IConstraint Smaller(); 132 133 /// <summary>sets the evaluation mode to identity comparison.</summary> 134 /// <remarks> 135 /// sets the evaluation mode to identity comparison. In this case only 136 /// objects having the same database identity will be included in the result set. 137 /// For example:<br/> 138 /// <code>Pilot pilot = new Pilot("Test Pilot1", 100);</code><br/> 139 /// <code>Car car = new Car("BMW", pilot);</code><br/> 140 /// <code>container.Store(car);</code><br/> 141 /// <code>// Change the name, the pilot instance stays the same</code><br/> 142 /// <code>pilot.SetName("Test Pilot2");</code><br/> 143 /// <code>// create a new car</code><br/> 144 /// <code>car = new Car("Ferrari", pilot);</code><br/> 145 /// <code>container.Store(car);</code><br/> 146 /// <code>IQuery query = container.Query();</code><br/> 147 /// <code>query.Constrain(typeof(Car));</code><br/> 148 /// <code>// All cars having pilot with the same database identity</code><br/> 149 /// <code>// will be retrieved. As we only created Pilot object once</code><br/> 150 /// <code>// it should mean all car objects</code><br/> 151 /// <code>query.Descend("_pilot").Constrain(pilot).Identity();</code><br/><br/> 152 /// </remarks> 153 /// <returns> 154 /// this 155 /// <see cref="Db4objects.Db4o.Query.IConstraint">Db4objects.Db4o.Query.IConstraint</see> 156 /// to allow the chaining of method calls. 157 /// </returns> Identity()158 IConstraint Identity(); 159 160 /// <summary>set the evaluation mode to object comparison (query by example).</summary> 161 /// <remarks>set the evaluation mode to object comparison (query by example).</remarks> 162 /// <returns> 163 /// this 164 /// <see cref="IConstraint">IConstraint</see> 165 /// to allow the chaining of method calls. 166 /// </returns> ByExample()167 IConstraint ByExample(); 168 169 /// <summary>sets the evaluation mode to "like" comparison.</summary> 170 /// <remarks> 171 /// sets the evaluation mode to "like" comparison. This mode will include 172 /// all objects having the constrain expression somewhere inside the string field. 173 /// For example:<br/> 174 /// <code>Pilot pilot = new Pilot("Test Pilot1", 100);</code><br/> 175 /// <code>container.Store(pilot);</code><br/> 176 /// <code> ...</code><br/> 177 /// <code>query.Constrain(typeof(Pilot));</code><br/> 178 /// <code>// All pilots with the name containing "est" will be retrieved</code><br/> 179 /// <code>query.Descend("name").Constrain("est").Like();</code><br/> 180 /// </remarks> 181 /// <returns> 182 /// this 183 /// <see cref="Db4objects.Db4o.Query.IConstraint">Db4objects.Db4o.Query.IConstraint</see> 184 /// to allow the chaining of method calls. 185 /// </returns> Like()186 IConstraint Like(); 187 188 /// <summary>Sets the evaluation mode to string contains comparison.</summary> 189 /// <remarks> 190 /// Sets the evaluation mode to string contains comparison. The contains comparison is case sensitive.<br/> 191 /// For example:<br/> 192 /// <code>Pilot pilot = new Pilot("Test Pilot1", 100);</code><br/> 193 /// <code>container.Store(pilot);</code><br/> 194 /// <code> ...</code><br/> 195 /// <code>query.Constrain(typeof(Pilot));</code><br/> 196 /// <code>// All pilots with the name containing "est" will be retrieved</code><br/> 197 /// <code>query.Descend("name").Constrain("est").Contains();</code><br/> 198 /// <see cref="Db4objects.Db4o.Query.IConstraint.Like">Like() for case insensitive string comparison</see> 199 /// </remarks> 200 /// <returns> 201 /// this 202 /// <see cref="Db4objects.Db4o.Query.IConstraint">Db4objects.Db4o.Query.IConstraint</see> 203 /// to allow the chaining of method calls. 204 /// </returns> Contains()205 IConstraint Contains(); 206 207 /// <summary>sets the evaluation mode to string StartsWith comparison.</summary> 208 /// <remarks> 209 /// sets the evaluation mode to string StartsWith comparison. 210 /// For example:<br/> 211 /// <code>Pilot pilot = new Pilot("Test Pilot0", 100);</code><br/> 212 /// <code>container.Store(pilot);</code><br/> 213 /// <code> ...</code><br/> 214 /// <code>query.Constrain(typeof(Pilot));</code><br/> 215 /// <code>query.Descend("name").Constrain("Test").StartsWith(true);</code><br/> 216 /// </remarks> 217 /// <param name="caseSensitive">comparison will be case sensitive if true, case insensitive otherwise 218 /// </param> 219 /// <returns> 220 /// this 221 /// <see cref="Db4objects.Db4o.Query.IConstraint">Db4objects.Db4o.Query.IConstraint</see> 222 /// to allow the chaining of method calls. 223 /// </returns> StartsWith(bool caseSensitive)224 IConstraint StartsWith(bool caseSensitive); 225 226 /// <summary>sets the evaluation mode to string EndsWith comparison.</summary> 227 /// <remarks> 228 /// sets the evaluation mode to string EndsWith comparison. 229 /// For example:<br/> 230 /// <code>Pilot pilot = new Pilot("Test Pilot0", 100);</code><br/> 231 /// <code>container.Store(pilot);</code><br/> 232 /// <code> ...</code><br/> 233 /// <code>query.Constrain(typeof(Pilot));</code><br/> 234 /// <code>query.Descend("name").Constrain("T0").EndsWith(false);</code><br/> 235 /// </remarks> 236 /// <param name="caseSensitive">comparison will be case sensitive if true, case insensitive otherwise 237 /// </param> 238 /// <returns> 239 /// this 240 /// <see cref="Db4objects.Db4o.Query.IConstraint">Db4objects.Db4o.Query.IConstraint</see> 241 /// to allow the chaining of method calls. 242 /// </returns> EndsWith(bool caseSensitive)243 IConstraint EndsWith(bool caseSensitive); 244 245 /// <summary>turns on Not() comparison.</summary> 246 /// <remarks> 247 /// turns on Not() comparison. All objects not fullfilling the constrain condition will be returned. 248 /// For example:<br/> 249 /// <code>Pilot pilot = new Pilot("Test Pilot1", 100);</code><br/> 250 /// <code>container.Store(pilot);</code><br/> 251 /// <code> ...</code><br/> 252 /// <code>query.Constrain(typeof(Pilot));</code><br/> 253 /// <code>query.Descend("name").Constrain("t0").EndsWith(true).Not();</code><br/> 254 /// </remarks> 255 /// <returns> 256 /// this 257 /// <see cref="Db4objects.Db4o.Query.IConstraint">Db4objects.Db4o.Query.IConstraint</see> 258 /// to allow the chaining of method calls. 259 /// </returns> Not()260 IConstraint Not(); 261 262 /// <summary> 263 /// returns the Object the query graph was constrained with to 264 /// create this 265 /// <see cref="IConstraint">IConstraint</see> 266 /// . 267 /// </summary> 268 /// <returns>Object the constraining object.</returns> GetObject()269 object GetObject(); 270 } 271 } 272