001/*
002// This software is subject to the terms of the Eclipse Public License v1.0
003// Agreement, available at the following URL:
004// http://www.eclipse.org/legal/epl-v10.html.
005// You must accept the terms of that agreement to use this software.
006//
007// Copyright (C) 2011-2011 Pentaho
008// All Rights Reserved.
009*/
010package mondrian.server;
011
012import mondrian.olap.Query;
013import mondrian.olap.SchemaReader;
014import mondrian.rolap.RolapConnection;
015import mondrian.rolap.RolapSchema;
016import mondrian.spi.ProfileHandler;
017
018import java.sql.SQLException;
019
020/**
021 * Internal context corresponding to a statement.
022 *
023 * <p>This interface is typically implemented by a MondrianOlap4jStatement,
024 * but not necessarily: statements may be created internally, not via olap4j.
025 *
026 * <p>Not part of Mondrian's public API. This class may change without
027 * notice.</p>
028 *
029 * @author jhyde
030 */
031public interface Statement {
032    /**
033     * Closes this statement.
034     */
035    void close();
036
037    /**
038     * Returns this statement's schema reader.
039     *
040     * @return Schema reader, not null
041     */
042    SchemaReader getSchemaReader();
043
044    /**
045     * Returns this statement's schema.
046     *
047     * @return Schema, not null
048     */
049    RolapSchema getSchema();
050
051    /**
052     * Returns this statement's connection.
053     *
054     * @return connection
055     */
056    RolapConnection getMondrianConnection();
057
058    Object getProperty(String name);
059
060    Query getQuery();
061
062    void setQuery(Query query);
063
064    /**
065     * Enables profiling.
066     *
067     * <p>Profiling information will be sent to the given writer when
068     * {@link mondrian.olap.Result#close()} is called.
069     *
070     * <p>If <tt>profileHandler</tt> is null, disables profiling.
071     *
072     * @param profileHandler Writer to which to send profiling information
073     */
074    void enableProfiling(ProfileHandler profileHandler);
075
076    ProfileHandler getProfileHandler();
077
078    /**
079     * Sets the timeout of this statement, in milliseconds.
080     *
081     * <p>Zero means no timeout.
082     *
083     * <p>Contrast with JDBC's {@link java.sql.Statement#setQueryTimeout(int)}
084     * method, which uses an {@code int} value and a granularity of seconds.
085     *
086     * @param timeoutMillis Timeout in milliseconds
087     */
088    void setQueryTimeoutMillis(long timeoutMillis);
089
090    /**
091     * Returns the query timeout of this statement, in milliseconds.
092     *
093     * <p>Zero means no timeout.</p>
094     *
095     * <p>Contrast with JDBC's {@link java.sql.Statement#getQueryTimeout()}
096     * method, which uses an {@code int} value and a granularity of seconds.
097     *
098     * @return Timeout in milliseconds
099     */
100    long getQueryTimeoutMillis();
101
102    /**
103     * Checks if either a cancel request has been issued on the query or
104     * the execution time has exceeded the timeout value (if one has been
105     * set).  Exceptions are raised if either of these two conditions are
106     * met.  This method should be called periodically during query execution
107     * to ensure timely detection of these events, particularly before/after
108     * any potentially long running operations.
109     *
110     * @deprecated This method will be removed in mondrian-4.0; use
111     *   {@link mondrian.server.Execution#checkCancelOrTimeout()}
112     */
113    void checkCancelOrTimeout();
114
115    /**
116     * Issues a cancel request on this statement.
117     *
118     * <p>Once the thread running the statement detects the cancel request,
119     * execution will throw an exception. See
120     * <code>BasicQueryTest.testCancel</code> for an example of usage of this
121     * method.</p>
122     *
123     * @throws java.sql.SQLException on error
124     */
125    void cancel() throws SQLException;
126
127    /**
128     * Returns execution context if currently executing, null otherwise.
129     *
130     * @return Execution context
131     */
132    Execution getCurrentExecution();
133
134    /**
135     * Ends the current execution.
136     *
137     * @param execution Execution; must match the execution that was started
138     *
139     * @throws IllegalArgumentException if not started,
140     *     or if execution does not match
141     */
142    void end(Execution execution);
143
144    /**
145     * Starts an execution.
146     *
147     * @param execution Execution context
148     */
149    void start(Execution execution);
150
151    /**
152     * Returns the ID of this statement, unique within the JVM.
153     *
154     * @return Unique ID of this statement
155     */
156    long getId();
157}
158
159// End Statement.java