001: /*
002: * $Header: /export/home/cvsroot/MyPersonalizerRepository/MyPersonalizer/Subsystems/Kernel/Sources/es/udc/mypersonalizer/kernel/model/query/executor/QueryExecutorDelegate.java,v 1.1.1.1 2004/03/25 12:08:37 fbellas Exp $
003: * $Revision: 1.1.1.1 $
004: * $Date: 2004/03/25 12:08:37 $
005: *
006: * =============================================================================
007: *
008: * Copyright (c) 2003, The MyPersonalizer Development Group
009: * (http://www.tic.udc.es/~fbellas/mypersonalizer/index.html) at
010: * University Of A Coruņa
011: * All rights reserved.
012: *
013: * Redistribution and use in source and binary forms, with or without
014: * modification, are permitted provided that the following conditions are met:
015: *
016: * - Redistributions of source code must retain the above copyright notice,
017: * this list of conditions and the following disclaimer.
018: *
019: * - Redistributions in binary form must reproduce the above copyright notice,
020: * this list of conditions and the following disclaimer in the documentation
021: * and/or other materials provided with the distribution.
022: *
023: * - Neither the name of the University Of A Coruņa nor the names of its
024: * contributors may be used to endorse or promote products derived from
025: * this software without specific prior written permission.
026: *
027: * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
028: * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
029: * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
030: * ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
031: * LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
032: * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
033: * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
034: * INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
035: * CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
036: * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
037: * POSSIBILITY OF SUCH DAMAGE.
038: *
039: */
040: package es.udc.mypersonalizer.kernel.model.query.executor;
041:
042: import es.udc.mypersonalizer.kernel.model.query.ast.Query;
043: import es.udc.mypersonalizer.kernel.model.query.ast.expr.PropertyListExpression;
044: import es.udc.mypersonalizer.kernel.util.exceptions.InternalErrorException;
045:
046: /**
047: * Interface for query executors.
048: * <p>
049: * Query executors are classes which execute the query (or part of it) on
050: * a given persistence type. They can make use of specific back-end features,
051: * process data in memory, or combine both approaches.
052: * <p>
053: * Implementations of this interface are assumed to be <b>not</b> thread-safe.
054: * <p>
055: * If the query spans multiple <code>MetaService</code>s, with different
056: * persistente methods, the implementations of this interface <em>must</em>
057: * use {@link es.udc.mypersonalizer.kernel.model.query.executor.QueryExecutorDelegateFactory}
058: * to obtain a suitable delegate and process its results. By using this
059: * mechanism, a query can be resolved by a chain of
060: * <code>QueryExecutorDelegate</code>s.
061: *
062: *
063: * @author Abel Muinho
064: * @since 1.0
065: */
066: public interface QueryExecutorDelegate {
067: // FIX: Ordering does not allow to specify direction (ascending / descending).
068: /**
069: * Performs a query using the information given.
070: * <p>
071: * Depending on the target property (the property referenced by the last
072: * step of the result clause), the value returned by a call to this method
073: * must be:
074: * <ol>
075: * <li>If the target is a <code>SimpleMetaProperty</code>, the
076: * result must be a list of correspondant
077: * <code>MetaSimplePropery</code> objects.</li>
078: * <li>If the target is a <code>MetaCompoundProperty</code>, the result
079: * must be a list of correspondant <code>MetaCompoundProperty</code>
080: * objects, with all its <em>real</em> children (that is, not including
081: * any <em>virtual</em> property, so <em>not</em> spanning different
082: * <code>MetaService</code>s.</li>
083: * <li>If the target is a <code>MetaService</code>, its root
084: * <code>MetaCompoundProperty</code> should be used.</li>
085: * </ol>
086: *
087: * @see es.udc.mypersonalizer.kernel.model.metainfo.MetaProperty
088: * @see es.udc.mypersonalizer.kernel.model.metainfo.MetaService
089: *
090: * @param query The query to evaluate.
091: * @return a list of properties as described by the result clause in the
092: * order specified by the order clause (or in document order if no
093: * order walker has been specified).
094: * @throws InternalErrorException if the query can not be executed.
095: */
096: public PropertyListExpression evaluate(Query query)
097: throws InternalErrorException;
098:
099: /**
100: * Similar to <code>evaluate(Query)</code> but allows to specify the
101: * range of properties to retrieve.
102: * <p>
103: * The <code>start</code> and <code>count</code> parameters are relative
104: * to the query order, as specified by the <code>order by</code> clause
105: * or the query executor delegate idea of <i>document order</i> if
106: * no explicit ordering has been requested.
107: * <p>
108: * <code>start</code> offset is <i>zero-based</i>.
109: *
110: * @see #evaluate(Query)
111: * @param query the query to evaluate.
112: * @param start the first property to be returned.
113: * @param count number of properties to be returned from <code>start</code>.
114: * @return a list of properties as described by the result clause in the
115: * order specified by the order clause (or in document order if no
116: * order walker has been specified).
117: * @throws InternalErrorException if the query can not be executed.
118: */
119: public PropertyListExpression evaluate(Query query, int start,
120: int count) throws InternalErrorException;
121: }
|