1. /*
  2. * @(#)Predicate.java 1.5 04/03/11
  3. *
  4. * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
  5. * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
  6. */
  7. package javax.sql.rowset;
  8. import javax.sql.*;
  9. import java.sql.*;
  10. /**
  11. * The standard interface that provides the framework for all
  12. * <code>FilteredRowSet</code> objects to describe their filters.
  13. * <p>
  14. * <h3>1.0 Background</h3>
  15. * The <code>Predicate</code> interface is a standard interface that
  16. * applications can implement to define the filter they wish to apply to a
  17. * a <code>FilteredRowSet</code> object. A <code>FilteredRowSet</code>
  18. * object consumes implementations of this interface and enforces the
  19. * constraints defined in the implementation of the method <code>evaluate</code>.
  20. * A <code>FilteredRowSet</code> object enforces the filter constraints in a
  21. * bi-directional manner: It outputs only rows that are within
  22. * the constraints of the filter; and conversely, it inserts, modifies, or updates
  23. * only rows that are within the constraints of the filter.
  24. *
  25. * <h3>2.0 Implementation Guidelines</h3>
  26. * In order to supply a predicate for the <code>FilteredRowSet</code>.
  27. * this interface must be implemented. At this time, the JDBC RowSet
  28. * Implementations (JSR-114) does not specify any standard filters definitions.
  29. * By specifying a standard means and mechanism for a range of filters to be
  30. * defined and deployed with both the reference and vendor implementations
  31. * of the <code>FilteredRowSet</code> interface, this allows for a flexible
  32. * and application motivated implementations of <code>Predicate</code> to emerge.
  33. * <p>
  34. * A sample implementation would look something like this:
  35. * <pre>
  36. * <code>
  37. * public class Range implements Predicate {
  38. *
  39. * private Object lo[];
  40. * private Object hi[];
  41. * private int idx[];
  42. *
  43. * public Range(Object[] lo, Object[] hi, int[] idx) {
  44. * this.lo = lo;
  45. * this.hi = hi;
  46. * this.idx = idx;
  47. * }
  48. *
  49. * public boolean evaluate(RowSet rs) {
  50. * CachedRowSet crs = (CachedRowSet)rs;
  51. * boolean bool1,bool2;
  52. *
  53. * // Check the present row determine if it lies
  54. * // within the filtering criteria.
  55. *
  56. * for (int i = 0; i < idx.length; i++) {
  57. *
  58. * if ((rs.getObject(idx[i]) >= lo[i]) &&
  59. * (rs.getObject(idx[i]) >= hi[i]) {
  60. * bool1 = true; // within filter constraints
  61. * } else {
  62. * bool2 = true; // outside of filter constraints
  63. * }
  64. * }
  65. *
  66. * if (bool2) {
  67. * return false;
  68. * } else {
  69. * return true;
  70. * }
  71. * }
  72. * </code>
  73. * </pre>
  74. * <P>
  75. * The example above implements a simple range predicate. Note, that
  76. * implementations should but are not required to provider <code>String</code>
  77. * and integer index based constructors to provide for JDBC RowSet Implementation
  78. * applications that use both column identification conventions.
  79. *
  80. * @author Jonathan Bruce, Amit Handa
  81. *
  82. */
  83. // <h3>3.0 FilteredRowSet Internals</h3>
  84. // internalNext, Frist, Last. Discuss guidelines on how to approach this
  85. // and cite examples in reference implementations.
  86. public interface Predicate {
  87. /**
  88. * This method is typically called a <code>FilteredRowSet</code> object
  89. * internal methods (not public) that control the <code>RowSet</code> object's
  90. * cursor moving from row to the next. In addition, if this internal method
  91. * moves the cursor onto a row that has been deleted, the internal method will
  92. * continue to ove the cursor until a valid row is found.
  93. *
  94. * @return <code>true</code> if there are more rows in the filter;
  95. * <code>false</code> otherwise
  96. */
  97. public boolean evaluate(RowSet rs);
  98. /**
  99. * This method is called by a <code>FilteredRowSet</code> object
  100. * to check whether the value lies between the filtering criterion (or criteria
  101. * if multiple constraints exist) set using the <code>setFilter()</code> method.
  102. * <P>
  103. * The <code>FilteredRowSet</code> object will use this method internally
  104. * while inserting new rows to a <code>FilteredRowSet</code> instance.
  105. *
  106. * @param value An <code>Object</code> value which needs to be checked,
  107. * whether it can be part of this <code>FilterRowSet</code> object.
  108. * @param column a <code>int</code> object that must match the
  109. * SQL index of a column in this <code>RowSet</code> object. This must
  110. * have been passed to <code>Predicate</code> as one of the columns
  111. * for filtering while initializing a <code>Predicate</code>
  112. * @return <code>true</code> ifrow value lies within the filter;
  113. * <code>false</code> otherwise
  114. * @throws SQLException if the column is not part of filtering criteria
  115. */
  116. public boolean evaluate(Object value, int column) throws SQLException;
  117. /**
  118. * This method is called by the <code>FilteredRowSet</code> object
  119. * to check whether the value lies between the filtering criteria set
  120. * using the setFilter method.
  121. * <P>
  122. * The <code>FilteredRowSet</code> object will use this method internally
  123. * while inserting new rows to a <code>FilteredRowSet</code> instance.
  124. *
  125. * @param value An <code>Object</code> value which needs to be checked,
  126. * whether it can be part of this <code>FilterRowSet</code>.
  127. *
  128. * @param columnName a <code>String</code> object that must match the
  129. * SQL name of a column in this <code>RowSet</code>, ignoring case. This must
  130. * have been passed to <code>Predicate</code> as one of the columns for filtering
  131. * while initializing a <code>Predicate</code>
  132. *
  133. * @return <code>true</code> if value lies within the filter; <code>false</code> otherwise
  134. *
  135. * @throws SQLException if the column is not part of filtering criteria
  136. */
  137. public boolean evaluate(Object value, String columnName) throws SQLException;
  138. }