KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > ws > jaxme > sqls > db2 > TableSpace


1 /*
2  * Copyright 2003, 2004 The Apache Software Foundation
3  *
4  * Licensed under the Apache License, Version 2.0 (the "License");
5  * you may not use this file except in compliance with the License.
6  * You may obtain a copy of the License at
7  *
8  * http://www.apache.org/licenses/LICENSE-2.0
9  *
10  * Unless required by applicable law or agreed to in writing, software
11  * distributed under the License is distributed on an "AS IS" BASIS,
12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13  * See the License for the specific language governing permissions and
14  * limitations under the License.
15
16  */

17 package org.apache.ws.jaxme.sqls.db2;
18
19 import java.util.Iterator JavaDoc;
20
21 import org.apache.ws.jaxme.sqls.SQLFactory;
22
23
24 /** <p>Interface of a DB2 TableSpace. An object of this kind is used to
25  * create a <code>CREATE TABLESPACE ...</code> statement.</p>
26  * <p>A TableSpace can be associated to a {@link BufferPool}. If it
27  * is, it inherits certain settings from the {@link BufferPool},
28  * in particular the {@link #getPageSize() pageSize}.</p>
29  * <p>A tablespace needs to know where data is stored physically. DB2
30  * distinguishes between two possible data locations: System managed
31  * (Files handled by the operating system) and Database managed (Files
32  * handled by the database or Devices). In the latter case the database
33  * will preallocate space for the files or devices, giving a slightly
34  * faster operation. On the other hand, database managed files cannot grow
35  * automatically.</p>
36  * <p>A tablespaces data location is called container. Any tablespace must
37  * have at least one container. Note, that one tablespace cannot have
38  * both system managed containers and database managed containers. If the
39  * first container is system managed, then all containers are, and vice
40  * versa.</p>
41  *
42  * @author <a HREF="mailto:joe@ispsoft.de">Jochen Wiedmann</a>
43  */

44 public interface TableSpace {
45   public interface Name extends SQLFactory.Ident {
46   }
47
48   /** <p>Interface of a TableSpace Container.</p>
49    */

50   public interface Container {
51     /** <p>Returns whether the container is system managed
52      * (aka an operating system file). If this is the case,
53      * the container may be casted to a
54      * {@link org.apache.ws.jaxme.sqls.db2.TableSpace.SystemManagedContainer}.</p>
55      */

56     public boolean isSystemManaged();
57     /** <p>Returns whether the container is database managed
58      * If this is the case, the container may be casted to a
59      * {@link org.apache.ws.jaxme.sqls.db2.TableSpace.DatabaseManagedContainer}.</p>
60      */

61     public boolean isDatabaseManaged();
62   }
63
64   /** <p>Interface of a system managed container, aka operating
65    * system file. A container may be casted to a SystemManagedContainer,
66    * if and only if <code>isSystemManaged() == true</code>.</p>
67    */

68   public interface SystemManagedContainer extends Container {
69     /** <p>Returns the containers file name.</p>
70      */

71     public String JavaDoc getFile();
72   }
73
74   /** <p>Interface of a database managed container. The container
75    * may be located in an operating system file with preallocated
76    * size or in a raw operating system device. A container may be
77    * casted to a DatabaseManagedContainer, if and only if
78    * <code>isDatabaseManaged() == true</code>.</p>
79    */

80   public interface DatabaseManagedContainer extends Container {
81     /** <p>Returns the containers file name or null, if the
82      * container is located in a raw device. In the latter case
83      * it is guaranteed, that {@link #getDevice()} returns a
84      * non-null value.</p>
85      */

86     public String JavaDoc getFile();
87     /** <p>Returns the containers device name or null, if the
88      * container is located in an operating system file. In the
89      * latter case it is guaranteed, that {@link #getDevice()}
90      * returns a non-null value.</p>
91      */

92     public String JavaDoc getDevice();
93     /** <p>Returns the containers size in pages.</p>
94      */

95     public long getNumOfPages();
96   }
97
98   /** <p>A DB2 TableSpace type. Valid types are either of
99    * {@link #REGULAR}, {@link #LONG}, {@link #SYSTEM_TEMPORARY}, or
100    * {@link #USER_TEMPORARY}. See the DB2 SQL reference in the section
101    * <code>CREATE TABLESPACE</code> for details on types.</p>
102    */

103   public class Type {
104      /** <p>REGULAR: Stores all data except for temporary tables.</p>
105       */

106     public static final Type REGULAR = new Type("REGULAR");
107     /** <p>LONG: Stores long or LOB table columns. It may also store
108      * structured type columns. The tablespace must be a DMS tablespace.</p>
109      */

110     public static final Type LONG = new Type("LONG");
111     /** <p>SYSTEM TEMPORARY: Stores temporary tables (work areas used
112      * by the database manager to perform operations such as sorts or
113      * joins). Note that a database must always have at least one
114      * <code>SYSTEM TEMPORARY</code> tablespace, as temporary tables
115      * can only be stored in such a tablespace. A temporary tablespace
116      * is created automatically when a database is created. See
117      * <code>CREATE DATABASE</code> in the Command Reference for more information.</p>
118      */

119     public static final Type SYSTEM_TEMPORARY = new Type("SYSTEM TEMPORARY");
120     /* <p>USER TEMPORARY: Stores declared global temporary tables.
121      * Note that no user temporary tablespaces exist when a database
122      * is created. At least one user temporary tablespace should be
123      * created with appropriate <code>USE</code> privileges, to allow
124      * definition of declared temporary tables.</p>
125      */

126     public static final Type USER_TEMPORARY = new Type("USER TEMPORARY");
127     private static final Type[] instances =
128       new Type[]{REGULAR, LONG, SYSTEM_TEMPORARY, USER_TEMPORARY};
129     private String JavaDoc name;
130     private Type(String JavaDoc pName) {
131       name = pName;
132     }
133     public String JavaDoc toString() { return name; }
134     public String JavaDoc getName() { return name; }
135     public boolean equals(Object JavaDoc pOther) {
136       return pOther != null && pOther instanceof Type &&
137               name.equals(((Type) pOther).name);
138     }
139     public int hashCode() { return name.hashCode(); }
140     public static Type[] getInstances() { return instances; }
141     public static Type valueOf(String JavaDoc pName) {
142       for (int i = 0; i < instances.length; i++) {
143         if (instances[i].name.equalsIgnoreCase(pName)) {
144           return instances[i];
145         }
146       }
147       throw new IllegalArgumentException JavaDoc("Invalid type name: " + pName);
148     }
149   }
150
151   /** <p>Returns the {@link org.apache.ws.jaxme.sqls.SQLFactory} that created this
152    * <code>TableSpace</code> object.</p>
153    */

154   public DB2SQLFactory getSQLFactory();
155
156   /** <p>Returns the tablespace name.
157    * Tablespace names must be unique in the database.</p>
158    */

159   public TableSpace.Name getName();
160
161   /** <p>Returns the tablespace type.</p>
162    */

163   public TableSpace.Type getType();
164
165   /** <p>Returns the tablespaces page size. If the <code>TableSpace</code>
166    * has an associated {@link BufferPool}, returns the BufferPool's page
167    * size. Otherwise returns the page size configured via
168    * {@link #setPageSize(PageSize)}.</p>
169    */

170   public PageSize getPageSize();
171
172   /** <p>Sets the tablespaces page size. This value will be ignored,
173    * if the <code>TableSpace</code> has an associated {@link BufferPool}.</p>
174    */

175   public void setPageSize(PageSize pSize);
176
177   /** <p>Returns the number of {@link #getPageSize() pageSize} pages that will
178    * be written to a container before skipping to the next container. The
179    * database manager cycles repeatedly through the containers as data is
180    * stored. Defaults to null, in which case the DB2 configuration
181    * parameter DFT_EXTENT_SZ applies.</p>
182    * </p>
183    */

184   public Long JavaDoc getExtentSize();
185
186   /** <p>Sets the number of {@link #getPageSize() pageSize} pages that will
187    * be written to a container before skipping to the next container. The
188    * database manager cycles repeatedly through the containers as data is
189    * stored. Defaults to null, in which case the DB2 configuration
190    * parameter DFT_EXTENT_SZ applies.</p>
191    * </p>
192    */

193   public void setExtentSize(Long JavaDoc pSize);
194
195   /** <p>Returns the number of {@link #getPageSize() pageSize} pages that will
196    * be read from the tablespace when data prefetching is being performed.
197    * Prefetching reads in data needed by a query prior to it being referenced
198    * by the query, so that the query need not wait for I/O to be performed.
199    * Defaults to null, in which case the DB2 configuration parameter
200    * DFT_PREFETCH_SZ applies.</p>
201    */

202   public Long JavaDoc getPrefetchSize();
203
204   /** <p>Sets the number of {@link #getPageSize() pageSize} pages that will
205    * be read from the tablespace when data prefetching is being performed.
206    * Prefetching reads in data needed by a query prior to it being referenced
207    * by the query, so that the query need not wait for I/O to be performed.
208    * Defaults to null, in which case the DB2 configuration parameter
209    * DFT_PREFETCH_SZ applies.</p>
210    */

211   public void setPrefetchSize(Long JavaDoc pSize);
212
213   /** <p>Returns the I/O controller overhead and disk seek and latency time, in
214    * milliseconds. The number should be an average for all containers that belong
215    * to the tablespace, if not the same for all containers. This value is used to
216    * determine the cost of I/O during query optimization. Defaults to null,
217    * in which case the DB2 default (24.1) applies.</p>
218    * </p>
219    */

220   public Number JavaDoc getOverhead();
221
222   /** <p>Sets the I/O controller overhead and disk seek and latency time, in
223    * milliseconds. The number should be an average for all containers that belong
224    * to the tablespace, if not the same for all containers. This value is used to
225    * determine the cost of I/O during query optimization. Defaults to null,
226    * in which case the DB2 default (24.1) applies.</p>
227    * </p>
228    */

229   public void setOverhead(Number JavaDoc pOverhead);
230
231   /** <p>Returns the transfer rate, which is defined as the time to read one page
232    * into memory, in milliseconds. The number shouldbe an average for all
233    * containers that belong to the tablespace, if not the same for all
234    * containers. This value is used to determine the cost of I/O during query
235    * optimization. Defaults to null, in which case the DB2 default (0.9)
236    * applies.</p>
237    */

238   public Number JavaDoc getTransferRate();
239
240   /** <p>Sets the transfer rate, which is defined as the time to read one page
241    * into memory, in milliseconds. The number shouldbe an average for all
242    * containers that belong to the tablespace, if not the same for all
243    * containers. This value is used to determine the cost of I/O during query
244    * optimization. Defaults to null, in which case the DB2 default (0.9)
245    * applies.</p>
246    */

247   public void setTransferRate(Number JavaDoc pNumber);
248
249   /** <p>Returns whether dropped tables in the specified tablespace may be
250    * recovered using the <code>RECOVER TABLE ON</code> option of the
251    * <code>ROLLFORWARD</code> command. This clause can only be specified
252    * for a {@link Type#REGULAR} tablespace (SQLSTATE 42613). For more
253    * information on recovering dropped tables, refer to the Administration
254    * Guide. Defaults to null, in which case the DB2 default applies.</p>
255    */

256   public Boolean JavaDoc hasDroppedTableRecovery();
257
258   /** <p>Sets whether dropped tables in the specified tablespace may be
259    * recovered using the <code>RECOVER TABLE ON</code> option of the
260    * <code>ROLLFORWARD</code> command. This clause can only be specified
261    * for a {@link Type#REGULAR} tablespace (SQLSTATE 42613). For more
262    * information on recovering dropped tables, refer to the Administration
263    * Guide. Defaults to null, in which case the DB2 default applies.</p>
264    */

265   public void setDroppedTableRecovery(Boolean JavaDoc pRecoverable);
266
267   /** <p>Creates a new system managed container with the given file.</p>
268    */

269   public Container newSystemManagedContainer(String JavaDoc pFile);
270
271   /** <p>Creates a new database managed container with the given file
272    * or device and the given number of pages.</p>
273    */

274   public Container newDatabaseManagedContainerInFile(String JavaDoc pFile, long pNumPages);
275
276   /** <p>Creates a new database managed container with the given raw
277    * operating system device and the given number of pages.</p>
278    */

279   public Container newDatabaseManagedContainerInDevice(String JavaDoc pDevice, long pNumPages);
280
281   /** <p>Returns an {@link Iterator} to the table spaces containers.
282    * Any element in the {@link java.util.Iterator} is an instance of
283    * {@link org.apache.ws.jaxme.sqls.db2.TableSpace.Container}, which
284    * was created using {@link #newSystemManagedContainer(String)},
285    * {@link #newDatabaseManagedContainerInFile(String, long)}, or
286    * {@link #newDatabaseManagedContainerInDevice(String, long)}.</p>
287    */

288   public Iterator JavaDoc getContainers();
289
290   /** <p>Sets the {@link BufferPool} used by this {@link TableSpace}.</p>
291    */

292   public void setBufferPool(BufferPool pBufferPool);
293
294   /** <p>Returns the {@link BufferPool} used by this {@link TableSpace}.</p>
295    */

296   public BufferPool getBufferPool();
297
298   /** <p>Returns whether this TableSpace is predefined by the system.</p>
299    */

300   public boolean isPredefined();
301 }
302
Popular Tags