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  ;
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   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   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   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   name;
130     private Type(String   pName) {
131       name = pName;
132     }
133     public String   toString() { return name; }
134     public String   getName() { return name; }
135     public boolean equals(Object   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   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  ("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   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   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   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   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   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   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   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   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   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   pRecoverable);
266 
267   /** <p>Creates a new system managed container with the given file.</p>
268    */
269   public Container newSystemManagedContainer(String   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   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   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   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
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags