001: /*
002: * Copyright 2004 Outerthought bvba and Schaubroeck nv
003: *
004: * Licensed under the Apache License, Version 2.0 (the "License");
005: * you may not use this file except in compliance with the License.
006: * You may obtain a copy of the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS,
012: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013: * See the License for the specific language governing permissions and
014: * limitations under the License.
015: */
016: package org.outerj.daisy.query.model;
017:
018: import org.outerj.daisy.repository.query.QueryException;
019: import org.outerj.daisy.query.EvaluationInfo;
020:
021: import java.sql.PreparedStatement;
022: import java.sql.SQLException;
023: import java.util.Locale;
024:
025: /**
026: * An expression which evaluates to some value.
027: */
028: public interface ValueExpr extends Expression {
029: /**
030: * Evaluates this expression for the given document and/or version.
031: *
032: * <p>The ExprDocData argument is optional. If an expressions needs access
033: * to document data, it should check ExprDocData is available and if not,
034: * throw a {@link ExprDocDataMissingException}.
035: *
036: * @param valueType Indicates the type of object to return. This parameter only matters
037: * when {@link #getValueType()} return QValueType.UNDEFINED. In other
038: * cases null can be supplied.
039: */
040: Object evaluate(QValueType valueType, ExprDocData data,
041: EvaluationInfo evaluationInfo) throws QueryException;
042:
043: /**
044: * Returns the ValueType of this expression, or null if undetermined.
045: */
046: QValueType getValueType();
047:
048: /**
049: * Returns true if this ValueExpr represents a symbolic identifier.
050: *
051: * A symbolic identifier is an identifier that identifies an object by name
052: * in the query, but uses an ID to search on the database.
053: *
054: * <p>If this method returns true, then {@link #translateSymbolic} can
055: * be called to convert the symbolic value to the test value.
056: */
057: boolean isSymbolicIdentifier();
058:
059: /**
060: * See {@link #isSymbolicIdentifier()}. This method should only be called
061: * if {@link #isSymbolicIdentifier()} returns true.
062: */
063: Object translateSymbolic(ValueExpr valueExpr,
064: EvaluationInfo evaluationInfo) throws QueryException;
065:
066: boolean isMultiValue();
067:
068: boolean isHierarchical();
069:
070: /**
071: * Returns true for ValueExpr's which cannot be searched on (i.e. no
072: * SQL can be generated) and which cannot be evaluated. Thus valueExpr's
073: * which can be used in the select and order by parts of a query, but
074: * not in the where part.
075: */
076: boolean isOutputOnly();
077:
078: /**
079: * Returns non-null if this ValueExpr is not fitted for use in ACL
080: * document selection expressions.
081: */
082: AclConditionViolation isAclAllowed();
083:
084: /**
085: * Generates any SQL conditions needed outside of the main value expression (which is
086: * generated using {@link #generateSqlValueExpr(StringBuilder, SqlGenerationContext)}).
087: *
088: * <p>Should throw an exception if this is an output-only ValueExpr.
089: *
090: * @return null if not applicable
091: */
092: String getSqlPreConditions(SqlGenerationContext context)
093: throws QueryException;
094:
095: /**
096: * Generates the SQL for this expression.
097: *
098: * <p>Should throw an exception if this is an output-only ValueExpr.
099: */
100: void generateSqlValueExpr(StringBuilder sql,
101: SqlGenerationContext context) throws QueryException;
102:
103: int bindPreConditions(PreparedStatement stmt, int bindPos,
104: EvaluationInfo evaluationInfo) throws SQLException,
105: QueryException;
106:
107: int bindValueExpr(PreparedStatement stmt, int bindPos,
108: QValueType valueType, EvaluationInfo evaluationInfo)
109: throws SQLException, QueryException;
110:
111: String getTitle(Locale locale);
112:
113: /**
114: * Get a textual representation of this expression, i.e. something that could be parsed
115: * again and give the same ValueExpr again.
116: *
117: * <p>If this requires effort to to build up (rather than returning a fixed string), it
118: * is recommended that implementations of this method cache the result for future fast
119: * retrievals.
120: */
121: String getExpression();
122:
123: /**
124: * Identifies the type of data returned from the
125: * {@link #getOutputValue(ExprDocData, EvaluationInfo)} method.
126: */
127: QValueType getOutputValueType();
128:
129: /**
130: * Returns the output value of this identifier for the document
131: * and version supplied via the ExprDocData object.
132: * For symbolic identifiers this will be different from the value returned by
133: * {@link #evaluate(QValueType, ExprDocData, EvaluationInfo)}.
134: * The version is allowed to be null.
135: */
136: Object getOutputValue(ExprDocData data,
137: EvaluationInfo evaluationInfo) throws QueryException;
138:
139: boolean canTestAppliesTo();
140:
141: /**
142: * Perform something in the context of this value expression.
143: */
144: void doInContext(SqlGenerationContext context,
145: ContextualizedRunnable runnable) throws QueryException;
146:
147: public static interface ContextualizedRunnable {
148: void run(SqlGenerationContext context) throws QueryException;
149: }
150:
151: ValueExpr clone();
152: }
|