| // Copyright 2008 Google Inc. |
| // |
| // Licensed under the Apache License, Version 2.0 (the "License"); |
| // you may not use this file except in compliance with the License. |
| // You may obtain a copy of the License at |
| // |
| // http://www.apache.org/licenses/LICENSE-2.0 |
| // |
| // Unless required by applicable law or agreed to in writing, software |
| // distributed under the License is distributed on an "AS IS" BASIS, |
| // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| // See the License for the specific language governing permissions and |
| // limitations under the License. |
| |
| package com.google.gwtorm.server; |
| |
| /** |
| * Application database definition and top-level schema access. |
| * |
| * <p>Applications should extend this interface and declare relation methods for each entity/table |
| * used. Relation methods must be marked with the {@link Relation} annotation and return an |
| * interface extending {@link Access}. At runtime the application extension of Schema will be |
| * automatically implemented with a generated class, providing implementations of the Access |
| * extensions from each of the declared relation methods. |
| * |
| * <p>Instances of a schema should be obtained through the {@link com.google.gwtorm.jdbc.Database} |
| * class on a pure-JDBC implementation and through <code>GWT.create()</code> on the GWT client side. |
| * |
| * <p>In the JDBC implementation each Schema instance wraps around a single JDBC Connection object. |
| * Therefore a Schema instance has a 1:1 relationship with an active database handle. |
| * |
| * <p>A Schema instance (as well as its returned Access instances) is not thread safe. Applications |
| * must provide their own synchronization, or ensure that at most 1 thread access a Schema instance |
| * (or any returned Access instance) at a time. The safest mapping is 1 schema instance per thread, |
| * never shared. |
| * |
| * <p>For example the OurDb schema creates two tables (identical structure) named <code>someFoos |
| * </code> and <code>otherFoos</code>: |
| * |
| * <pre> |
| * public interface FooAccess extends Access<Foo, Foo.Key> { |
| * @PrimaryKey("key") |
| * Foo byKey(Foo.Key k) throws OrmException; |
| * } |
| * public interface OurDb extends Schema { |
| * @Relation |
| * FooAccess someFoos(); |
| * |
| * @Relation |
| * FooAccess otherFoos(); |
| * } |
| * </pre> |
| */ |
| public interface Schema extends AutoCloseable { |
| /** Commit a pending transaction. */ |
| public void commit() throws OrmException; |
| |
| /** Abort a pending transaction, if one is already in progress, otherwise nop. */ |
| public void rollback() throws OrmException; |
| |
| /** |
| * Add any missing columns, create any missing tables or sequences. |
| * |
| * <p>This method does not drop any unused columns or tables, leaving them intact for applications |
| * to continue to query after the update. Any unused columns that are NOT NULL are altered to |
| * accept NULL. |
| * |
| * @param e executor to perform (or log) the statements. |
| * @throws OrmException one or more objects could not be added to the schema. |
| */ |
| public void updateSchema(StatementExecutor e) throws OrmException; |
| |
| /** |
| * Drop any unused columns, tables, or sequences. |
| * |
| * <p>This method destroys data, as columns may be removed entirely. |
| * |
| * @param e executor to perform (or log) the statements. |
| * @throws OrmException one or more drops could not be completed. |
| */ |
| public void pruneSchema(StatementExecutor e) throws OrmException; |
| |
| /** @return access interface for each declared relation. */ |
| public Access<?, ?>[] allRelations(); |
| |
| /** Close the schema and release all resources. */ |
| @Override |
| public void close(); |
| } |