01: /*
02: * Copyright (C) <2005> <Steve Woodcock>
03: * Created on 07-Oct-2004
04: *
05: */
06: package com.jofti.api;
07:
08: /**
09:
10: *
11: * Root interface for query objects. All IndexQueries will implement this interface, but not all are required
12: * to provide implementations of the optional parameter setting methods.<p>
13: *
14: * @author Steve Woodcock<br>
15: * @version 1.7<p>
16: */
17: public interface IndexQuery {
18:
19: /**
20: * <p>
21: * Sets a parameter on a Query by name. The name should match a String representation of the
22: * parameter in the query implementation. The format of the name is defined by the type of query.
23: * </p>
24: * <p>
25: * The method returns the IndexQuery in order to allow method chaining for parameter setting.
26: * </p>
27: * @param name - the name for the parameter.
28: * @param value - the Object that is used to bind to the parameter.
29: * @return - The indexQuery that the parameter was set on.
30: */
31: public IndexQuery setParameter(String name, Object value);
32:
33: /**
34: * <p>
35: * Sets a parameter on a Query by name. The name should match the numeric position of the
36: * parameter in the query implmentation. The format of the name is defined by the type of query.
37: * </p>
38: * <p>
39: * The method returns the IndexQuery in order to allow method chaining for parameter setting.
40: * </p>
41: * @param position - the position for the parameter.
42: * @param value - the Object that is used to bind to the parameter.
43: * @return - The indexQuery that the parameter was set on.
44: */
45: public IndexQuery setParameter(int position, Object value);
46:
47: /**
48: * <p>
49: * Sets a maximum number of results to return in the query. If the results are not ordered then
50: * repeated calling of the method could return different results irrespective of data changes.
51: * </p>
52: * <p>
53: * When ordering is set repeated calls with this value set will return the same results providing
54: * that the data has not changed. However, in order to provide ordering the full result set must
55: * be evaluated and are therefore loaded into memory. The results falling outside the return range will then be discarded.
56: * </p>
57: * <p>
58: * A negative value will return a runtime IllegalArgumentException. Zero is equivalent to all results. Setting the value to more than
59: * the number of results found will results in all results being returned.
60: * The method returns the IndexQuery in order to allow method chaining for parameter setting.
61: * </p>
62: * @param maxResults - the maximum number of results to return.
63: * @return - The indexQuery that the parameter was set on.
64: */
65: public IndexQuery setMaxResults(int maxResults);
66:
67: /**
68: * <p>
69: * Sets the first result number to be returned. If this is used in conjunction with maxResults then a paging type
70: * mechanism can be emulated (providing the results are ordered). A negative value will result in a runtimeException and setting the value
71: * larger than the number of results will result in zero results returned.
72: * </p>
73: * <p>
74: * The method returns the IndexQuery in order to allow method chaining for parameter setting.
75: * </p>
76: * @param firstResult - the position of the first result - this is 0 indexed.
77: * @return - The indexQuery that the parameter was set on.
78: */
79: public IndexQuery setFirstResult(int firstResult);
80:
81: }
|