001: /*
002:
003: Derby - Class org.apache.derby.iapi.sql.execute.RunTimeStatistics
004:
005: Licensed to the Apache Software Foundation (ASF) under one or more
006: contributor license agreements. See the NOTICE file distributed with
007: this work for additional information regarding copyright ownership.
008: The ASF licenses this file to you under the Apache License, Version 2.0
009: (the "License"); you may not use this file except in compliance with
010: the License. You may obtain a copy of the License at
011:
012: http://www.apache.org/licenses/LICENSE-2.0
013:
014: Unless required by applicable law or agreed to in writing, software
015: distributed under the License is distributed on an "AS IS" BASIS,
016: WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
017: See the License for the specific language governing permissions and
018: limitations under the License.
019:
020: */
021:
022: package org.apache.derby.iapi.sql.execute;
023:
024: import java.io.Serializable;
025:
026: import java.sql.Time;
027: import java.sql.Timestamp;
028:
029: /**
030:
031: * A RunTimeStatistics object is a representation of the query execution plan and run
032: * time statistics for a java.sql.ResultSet.
033: *
034: * A query execution plan is a tree
035: * of execution nodes. There are a number of possible node types. Statistics
036: * are accumulated during execution at each node. The types of statistics include
037: * the amount of time spent in specific operations (if STATISTICS TIMING is SET ON),
038: * the number of rows passed to the node by its child(ren) and the number of rows
039: * returned by the node to its parent. (The exact statistics are specific to each
040: * node type.)
041: * <P>
042: * RunTimeStatistics is most meaningful for DML statements (SELECT, INSERT, DELETE
043: * and UPDATE).
044: *
045: */
046: public interface RunTimeStatistics {
047: /**
048: * Get the total compile time for the associated query in milliseconds.
049: * Compile time can be divided into parse, bind, optimize and generate times.
050: * <P>
051: * 0 is returned if STATISTICS TIMING is not SET ON.
052: *
053: * @return The total compile time for the associated query in milliseconds.
054: */
055: public long getCompileTimeInMillis();
056:
057: /**
058: * Get the parse time for the associated query in milliseconds.
059: * <P>
060: * 0 is returned if STATISTICS TIMING is not SET ON.
061: *
062: * @return The parse time for the associated query in milliseconds.
063: */
064: public long getParseTimeInMillis();
065:
066: /**
067: * Get the bind time for the associated query in milliseconds.
068: *
069: * @return The bind time for the associated query in milliseconds.
070: */
071: public long getBindTimeInMillis();
072:
073: /**
074: * Get the optimize time for the associated query in milliseconds.
075: * <P>
076: * 0 is returned if STATISTICS TIMING is not SET ON.
077: *
078: * @return The optimize time for the associated query in milliseconds.
079: */
080: public long getOptimizeTimeInMillis();
081:
082: /**
083: * Get the generate time for the associated query in milliseconds.
084: * <P>
085: * 0 is returned if STATISTICS TIMING is not SET ON.
086: *
087: * @return The generate time for the associated query in milliseconds.
088: */
089: public long getGenerateTimeInMillis();
090:
091: /**
092: * Get the execute time for the associated query in milliseconds.
093: * <P>
094: * 0 is returned if STATISTICS TIMING is not SET ON.
095: *
096: * @return The execute time for the associated query in milliseconds.
097: */
098: public long getExecuteTimeInMillis();
099:
100: /**
101: * Get the timestamp for the beginning of query compilation.
102: * <P>
103: * A null is returned if STATISTICS TIMING is not SET ON.
104: *
105: * @return The timestamp for the beginning of query compilation.
106: */
107: public Timestamp getBeginCompilationTimestamp();
108:
109: /**
110: * Get the timestamp for the end of query compilation.
111: * <P>
112: * A null is returned if STATISTICS TIMING is not SET ON.
113: *
114: * @return The timestamp for the end of query compilation.
115: */
116: public Timestamp getEndCompilationTimestamp();
117:
118: /**
119: * Get the timestamp for the beginning of query execution.
120: * <P>
121: * A null is returned if STATISTICS TIMING is not SET ON.
122: *
123: * @return The timestamp for the beginning of query execution.
124: */
125: public Timestamp getBeginExecutionTimestamp();
126:
127: /**
128: * Get the timestamp for the end of query execution.
129: * <P>
130: * A null is returned if STATISTICS TIMING is not SET ON.
131: *
132: * @return The timestamp for the end of query execution.
133: */
134: public Timestamp getEndExecutionTimestamp();
135:
136: /**
137: * Get the name of the associated query or statement.
138: * (This will be an internally generated name if the
139: * user did not assign a name.)
140: *
141: * @return The name of the associated query or statement.
142: */
143: public String getStatementName();
144:
145: /**
146: * Get the name of the Stored Prepared Statement used
147: * for the statement. This method returns
148: * a value only for <i>EXECUTE STATEMENT</i> statements;
149: * otherwise, returns null.
150: * <p>
151: * Note that the name is returned in the schema.name
152: * format (e.g. APP.MYSTMT).
153: *
154: * @return The Stored Prepared Statement name of
155: * the associated statement, or null if it is not an EXECUTE
156: * STATEMENT statement.
157: */
158: public String getSPSName();
159:
160: /**
161: * Get the text for the associated query or statement.
162: *
163: * @return The text for the associated query or statement.
164: */
165: public String getStatementText();
166:
167: /**
168: * Get a String representation of the execution plan
169: * for the associated query or statement.
170: *
171: * @return The execution plan for the associated query or statement.
172: */
173: public String getStatementExecutionPlanText();
174:
175: /**
176: * Get a String representation of the information on the nodes
177: * relating to table and index scans from the execution plan for
178: * the associated query or statement.
179: *
180: * @return The nodes relating to table and index scans
181: * from the execution plan for the associated query or statement.
182: */
183: public String getScanStatisticsText();
184:
185: /**
186: * Get a String representation of the information on the nodes
187: * relating to table and index scans from the execution plan for
188: * the associated query or statement for a particular table.
189: * <P>
190: * @param tableName The table for which user desires statistics.
191: * <P>
192: * @return The nodes relating to table and index scans
193: * from the execution plan for the associated query or statement.
194: */
195: public String getScanStatisticsText(String tableName);
196:
197: /**
198: * Get the estimated row count for the number of rows returned
199: * by the associated query or statement.
200: *
201: * @return The estimated number of rows returned by the associated
202: * query or statement.
203: */
204: public double getEstimatedRowCount();
205: }
|