001: /*
002:
003: This software is OSI Certified Open Source Software.
004: OSI Certified is a certification mark of the Open Source Initiative.
005:
006: The license (Mozilla version 1.0) can be read at the MMBase site.
007: See http://www.MMBase.org/license
008:
009: */
010: package org.mmbase.storage.search.implementation.database;
011:
012: import org.mmbase.storage.search.*;
013:
014: /**
015: * Interface for handler classes that are used to create SQL string
016: * representations of {@link SearchQuery SearchQuery} objects.
017: * <p>
018: * A number of <code>SqlHandler</code> objects can create a chain of handlers,
019: * following the <em>Chain Of Responsibility</em> design pattern.
020: * <p>
021: * In short:
022: * <ul>
023: * <li>A chain is formed of <code>SqlHandler</code> objects, where each
024: * element in the chain, except the last one, is called a <em>chained</em>
025: * handler.
026: * Each chained handler has a <em>successor</em>, which is the next element
027: * in the chain.
028: * <li>The first element receives all requests first (a <em>request</em> =
029: * call of one of the methods in the interface).
030: * When a chained element receives a request, it can either handle it or pass
031: * it on to its successor.
032: * <li>The last element in the chain, handles all remaining requests.
033: * </ul>
034: * <p>
035: * Each handler in the chain adds functionality to its successor(s),
036: * in a way similar to subclassing. The chained design
037: * enables a chain of handlers to be configured and created
038: * at runtime.
039: * <p>
040: * In addition to the methods defined in the interface, the concrete
041: * <code>SqlHandler</code> class for the last element in the chain
042: * is required to have a constructor with this signature:
043: * <blockquote><code>
044: public <constructor>(Map disallowedValues) { .. }
045: * </code></blockquote>
046: * where <code>disallowedValues</code> is a map that maps disallowed
047: * table/fieldnames to allowed alternatives.
048: * <p>
049: * The concrete <code>SqlHandler</code> class for the other, chained,
050: * elements in the chain are required to have a constructor
051: * with this signature:
052: * <blockquote><code>
053: public <constructor>(SqlHandler successor) { .. }
054: * </code></blockquote>
055: * where <code>successor</code> is the successor in the chain
056: * of responsibility.
057: *
058: * @author Rob van Maris
059: * @version $Id: SqlHandler.java,v 1.8 2007/06/12 10:59:41 michiel Exp $
060: * @since MMBase-1.7
061: */
062: public interface SqlHandler {
063: /**
064: * Represents a SearchQuery object as a string in SQL format,
065: * using the database configuration.
066: *
067: * @param query The searchquery.
068: * @param firstInChain The first element in the chain of handlers.
069: * At some point <code>appendQueryBodyToSql() will have
070: * to be called on this handler, to generate the body of the query.
071: * @return SQL string representation of the query.
072: */
073: String toSql(SearchQuery query, SqlHandler firstInChain)
074: throws SearchQueryException;
075:
076: /**
077: * Represents body of a SearchQuery object as a string in SQL format,
078: * using the database configuration. Appends this to a stringbuffer.
079: * <br />
080: * The body of the SQL query string is defined as the substring containing
081: * fields, tables, constraints and orders.
082: *
083: * @param sb The stringbuffer to append to.
084: * @param query The searchquery.
085: * @param firstInChain The first element in the chain of handlers.
086: * At some point <code>appendConstraintToSql()</code> will have
087: * to be called on this handler, to generate the constraints in
088: * the query.
089: */
090: public void appendQueryBodyToSql(StringBuilder sb,
091: SearchQuery query, SqlHandler firstInChain)
092: throws SearchQueryException;
093:
094: /**
095: * Represents Constraint object, that is not a CompositeConstraint,
096: * as a constraint in SQL format, appending the result to a stringbuffer.
097: * When it is part of a composite expression, it will be surrounded by
098: * parenthesis when needed.
099: *
100: * @param sb The stringbuffer to append to.
101: * @param constraint The (non-composite) constraint.
102: * @param query The searchquery containing the constraint.
103: * @param inverse True when the inverse constraint must be represented,
104: * false otherwise.
105: * @param inComposite True when the constraint is part of
106: * a composite expression.
107: */
108: void appendConstraintToSql(StringBuilder sb, Constraint constraint,
109: SearchQuery query, boolean inverse, boolean inComposite)
110: throws SearchQueryException;
111:
112: /**
113: * Gets the level at which a feature is supported for a query
114: * by this handler. This is one of either:
115: * <ul>
116: * <li>{@link SearchQueryHandler#SUPPORT_NONE SUPPORT_NONE}
117: * <li>{@link SearchQueryHandler#SUPPORT_WEAK SUPPORT_WEAK}
118: * <li>{@link SearchQueryHandler#SUPPORT_NORMAL SUPPORT_NORMAL}
119: * <li>{@link SearchQueryHandler#SUPPORT_OPTIMAL SUPPORT_OPTIMAL}
120: * </ul>
121: * Given the choice, the query handler with the highest level of support is prefered.
122: */
123: public int getSupportLevel(int feature, SearchQuery query)
124: throws SearchQueryException;
125:
126: /**
127: * Gets the level at which a constraint is supported for a query
128: * by this handler. This is one of either:
129: * <ul>
130: * <li>{@link SearchQueryHandler#SUPPORT_NONE SUPPORT_NONE}
131: * <li>{@link SearchQueryHandler#SUPPORT_WEAK SUPPORT_WEAK}
132: * <li>{@link SearchQueryHandler#SUPPORT_NORMAL SUPPORT_NORMAL}
133: * <li>{@link SearchQueryHandler#SUPPORT_OPTIMAL SUPPORT_OPTIMAL}
134: * </ul>
135: * Given the choice, the query handler with the highest level of support is prefered.
136: */
137: public int getSupportLevel(Constraint constraint, SearchQuery query)
138: throws SearchQueryException;
139:
140: /**
141: * Maps string to value that is allowed as table or field name.
142: *
143: * @deprecated use {@link org.mmbase.storage.StorageManagerFactory#getStorageIdentifier}
144: * @param value The string value.
145: * @return The mapped value.
146: */
147: public String getAllowedValue(String value);
148: }
|