SqlHandler


1   /*
2   
3   This software is OSI Certified Open Source Software.
4   OSI Certified is a certification mark of the Open Source Initiative.
5   
6   The license (Mozilla version 1.0) can be read at the MMBase site.
7   See http://www.MMBase.org/license
8   
9   */
10  package org.mmbase.storage.search.implementation.database;
11  
12  import org.mmbase.storage.search.*;
13  /**
14   * Interface for handler classes that are used to create SQL string
15   * representations of {@link SearchQuery SearchQuery} objects.
16   * <p>
17   * A number of <code>SqlHandler</code> objects can create a chain of handlers,
18   * following the <em>Chain Of Responsibility</em> design pattern.
19   * <p>
20   * In short:
21   * <ul>
22   * <li>A chain is formed of <code>SqlHandler</code> objects, where each
23   * element in the chain, except the last one, is called a <em>chained</em>
24   * handler.
25   * Each chained handler has a <em>successor</em>, which is the next element
26   * in the  chain.
27   * <li>The first element receives all requests first (a <em>request</em> =
28   * call of one of the methods in the interface).
29   * When a chained element receives a request, it can either handle it or pass
30   * it on to its successor.
31   * <li>The last element in the chain, handles all remaining requests.
32   * </ul>
33   * <p>
34   * Each handler in the chain adds functionality to its successor(s),
35   * in a way similar to subclassing. The chained design
36   * enables a chain of handlers to be configured and created
37   * at runtime.
38   * <p>
39   * In addition to the methods defined in the interface, the concrete
40   * <code>SqlHandler</code> class for the last element in the chain
41   * is required to have a constructor with this signature:
42   * <blockquote><code>
43      public &lt;constructor&gt;(Map disallowedValues) { .. }
44   * </code></blockquote>
45   * where <code>disallowedValues</code> is a map that maps disallowed
46   * table/fieldnames to allowed alternatives.
47   * <p>
48   * The concrete <code>SqlHandler</code> class for the other, chained,
49   * elements in the chain are required to have a constructor
50   * with this signature:
51   * <blockquote><code>
52      public &lt;constructor&gt;(SqlHandler successor) { .. }
53   * </code></blockquote>
54   * where <code>successor</code> is the successor in the chain
55   * of responsibility.
56   *
57   * @author  Rob van Maris
58   * @version $Id: SqlHandler.java,v 1.7 2005/10/01 20:11:03 michiel Exp $
59   * @since MMBase-1.7
60   */
61  public interface SqlHandler {
62      /**
63       * Represents a SearchQuery object as a string in SQL format,
64       * using the database configuration.
65       *
66       * @param query The searchquery.
67       * @param firstInChain The first element in the chain of handlers.
68       *        At some point <code>appendQueryBodyToSql() will have
69       *        to be called on this handler, to generate the body of the query.
70       * @return SQL string representation of the query.
71       */
72      String   toSql(SearchQuery query, SqlHandler firstInChain) throws SearchQueryException;
73  
74      /**
75       * Represents body of a SearchQuery object as a string in SQL format,
76       * using the database configuration. Appends this to a stringbuffer.
77       * <br />
78       * The body of the SQL query string is defined as the substring containing
79       * fields, tables, constraints and orders.
80       *
81       * @param sb The stringbuffer to append to.
82       * @param query The searchquery.
83       * @param firstInChain The first element in the chain of handlers.
84       *        At some point <code>appendConstraintToSql()</code> will have
85       *        to be called on this handler, to generate the constraints in
86       *        the query.
87       */
88      public void appendQueryBodyToSql(StringBuffer   sb, SearchQuery query, SqlHandler firstInChain) throws SearchQueryException;
89  
90      /**
91       * Represents Constraint object, that is not a CompositeConstraint,
92       * as a constraint in SQL format, appending the result to a stringbuffer.
93       * When it is part of a composite expression, it will be surrounded by
94       * parenthesis when needed.
95       *
96       * @param sb The stringbuffer to append to.
97       * @param constraint The (non-composite) constraint.
98       * @param query The searchquery containing the constraint.
99       * @param inverse True when the inverse constraint must be represented,
100      *        false otherwise.
101      * @param inComposite True when the constraint is part of
102      *        a composite expression.
103      */
104     void appendConstraintToSql(StringBuffer   sb, Constraint constraint,
105     SearchQuery query, boolean inverse, boolean inComposite)
106     throws SearchQueryException;
107 
108     /**
109      * Gets the level at which a feature is supported for a query
110      * by this handler. This is one of either:
111      * <ul>
112      * <li>{@link SearchQueryHandler#SUPPORT_NONE SUPPORT_NONE}
113      * <li>{@link SearchQueryHandler#SUPPORT_WEAK SUPPORT_WEAK}
114      * <li>{@link SearchQueryHandler#SUPPORT_NORMAL SUPPORT_NORMAL}
115      * <li>{@link SearchQueryHandler#SUPPORT_OPTIMAL SUPPORT_OPTIMAL}
116      * </ul>
117      * Given the choice, the query handler with the highest level of support is prefered.
118      */
119     public int getSupportLevel(int feature, SearchQuery query)
120     throws SearchQueryException;
121 
122     /**
123      * Gets the level at which a constraint is supported for a query
124      * by this handler. This is one of either:
125      * <ul>
126      * <li>{@link SearchQueryHandler#SUPPORT_NONE SUPPORT_NONE}
127      * <li>{@link SearchQueryHandler#SUPPORT_WEAK SUPPORT_WEAK}
128      * <li>{@link SearchQueryHandler#SUPPORT_NORMAL SUPPORT_NORMAL}
129      * <li>{@link SearchQueryHandler#SUPPORT_OPTIMAL SUPPORT_OPTIMAL}
130      * </ul>
131      * Given the choice, the query handler with the highest level of support is prefered.
132      */
133     public int getSupportLevel(Constraint constraint, SearchQuery query)
134     throws SearchQueryException;
135 
136     /**
137      * Maps string to value that is allowed as table or field name.
138      *
139      * @deprecated use {@link org.mmbase.storage.StorageManagerFactory#getStorageIdentifier}
140      * @param value The string value.
141      * @return The mapped value.
142      */
143     public String   getAllowedValue(String   value);
144 }
145
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags