KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > opensubsystems > core > persist > db > DatabaseSchema


1 /*
2  * Copyright (c) 2003 - 2007 OpenSubsystems s.r.o. Slovak Republic. All rights reserved.
3  *
4  * Project: OpenSubsystems
5  *
6  * $Id: DatabaseSchema.java,v 1.14 2007/01/10 05:10:44 bastafidli Exp $
7  *
8  * This program is free software; you can redistribute it and/or modify
9  * it under the terms of the GNU General Public License as published by
10  * the Free Software Foundation; version 2 of the License.
11  *
12  * This program is distributed in the hope that it will be useful,
13  * but WITHOUT ANY WARRANTY; without even the implied warranty of
14  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
15  * GNU General Public License for more details.
16  *
17  * You should have received a copy of the GNU General Public License
18  * along with this program; if not, write to the Free Software
19  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
20  */
21
22 package org.opensubsystems.core.persist.db;
23
24 import java.sql.Connection JavaDoc;
25 import java.sql.SQLException JavaDoc;
26
27 import org.opensubsystems.core.error.OSSException;
28
29 /**
30  * Interface representing database schema, which is set of related database
31  * objects such as tables, constraints and indexes. One database instance
32  * will usually consists of multiple schemas coresponding to components used
33  * in the application. Each component or subsystem will provide one or multiple
34  * database schemas, which will be responsible for creation of all database
35  * structures for this components, for the upgrade of existing database
36  * structures to the latest version and also will encapsulate all specific
37  * database dependent information (such as database dependent queries).
38  *
39  * @version $Id: DatabaseSchema.java,v 1.14 2007/01/10 05:10:44 bastafidli Exp $
40  * @author Miro Halas
41  * @code.reviewer Miro Halas
42  * @code.reviewed 1.6 2006/07/21 22:47:38 jlegeny
43  */
44 public interface DatabaseSchema
45 {
46    // Accessors ////////////////////////////////////////////////////////////////
47
48    /**
49     * Get the name of this database schema.
50     *
51     * @return String - name which uniquely identifies this schema.
52     */
53    String JavaDoc getName(
54    );
55    
56    /**
57     * Get the current (most recent) version of database schema.
58     *
59     * @return int - most current version of the schema
60     */
61    int getVersion(
62    );
63
64    /**
65     * Check if the the data object belongs to a domain or not. If data object
66     * belongs to a domain, its table contains DOMAIN_ID column, which should
67     * be checked in generated SQL for this data type against the current call
68     * context domain.
69     *
70     * The assumption is that if the schema is managing multiple data objects
71     * and one of them is in domain then all of them are in domain (and vice
72     * versa) since it doesn't make sense for closely related data objects to do
73     * not exists in the same domain at the same time.
74     *
75     * @return boolean - true if data object belongs to domain, false otherwise
76     */
77    boolean isInDomain();
78    
79    // Lifecycle events /////////////////////////////////////////////////////////
80
81    /**
82     * Create the schema.
83     *
84     * @param cntDBConnection - valid connection to database
85     * @param strUserName - name of user who will be accessing this table
86     * @throws SQLException - problem creating the database schema
87     * @throws OSSException - problem creating the database schema
88     */
89    void create(
90       Connection JavaDoc cntDBConnection,
91       String JavaDoc strUserName
92    ) throws SQLException JavaDoc, OSSException;
93
94    /**
95     * Upgrade the schema.
96     *
97     * @param cntDBConnection - valid connection to database
98     * @param strUserName - name of user who will be accessing this table
99     * @param iOriginalVersion - original version from which to upgrade
100     * @throws SQLException - problem creating the database schema
101     */
102    void upgrade(
103       Connection JavaDoc cntDBConnection,
104       String JavaDoc strUserName,
105       int iOriginalVersion
106    ) throws SQLException JavaDoc;
107
108    /**
109     * Get list of database schemas which this schema depends on. These schemas
110     * will be created and initialized before this schema is initialized. This
111     * way if this schema has relationships (foreign keys, stored procedure
112     * access) with the other schemas, they are guaranteed to exist before this
113     * schema is created.
114     *
115     * @return DatabaseSchema[] - array of DatabaseSchema instances
116     * @throws OSSException - database cannot be started.
117     */
118    DatabaseSchema[] getDependentSchemas(
119    ) throws OSSException;
120    
121    /**
122     * Handle SQL Exception caused by some database operations.
123     *
124     * @param exc - sql exception to be handled
125     * @param dbConnection - database connection used when the exception occured
126     * @param iOperationType - type of the operation that caused the exception,
127     * see DatabaseOperations for possible values
128     * @param iDataType - data type the data object represents (e.g if this is
129     * type user and data is Integer, that means it is id
130     * of user object). This is one of the DataConstant
131     * constants.
132     * @param data - data object the exception is handled for
133     * @throws OSSException - problem handling exception
134     */
135    void handleSQLException(
136       SQLException JavaDoc exc,
137       Connection JavaDoc dbConnection,
138       int iOperationType,
139       int iDataType,
140       Object JavaDoc data
141    ) throws OSSException;
142 }
143
Popular Tags