com.google.gwtorm.server.Schema Maven / Gradle / Ivy
// 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.
*
* 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.
*
* Instances of a schema should be obtained through the
* {@link com.google.gwtorm.jdbc.Database} class on a pure-JDBC implementation
* and through GWT.create() on the GWT client side.
*
* 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.
*
* 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.
*
* For example the OurDb schema creates two tables (identical structure) named
* someFoos and otherFoos:
*
*
* 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();
* }
*
*/
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.
*
* 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.
*
* 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();
}