add SchemaManager

see jakartaee#399
gavinking · Aug 10, 2023 · e47f44f · e47f44f
1 parent 4daf494
commit e47f44f
Show file tree

Hide file tree

Showing 2 changed files with 98 additions and 0 deletions.
diff --git a/api/src/main/java/jakarta/persistence/EntityManagerFactory.java b/api/src/main/java/jakarta/persistence/EntityManagerFactory.java
@@ -11,6 +11,7 @@
  */
 
 // Contributors:
+//     Gavin King      - 3.2
 //     Linda DeMichiel - 2.1
 //     Linda DeMichiel - 2.0
 
@@ -167,6 +168,17 @@ public interface EntityManagerFactory extends AutoCloseable {
      */
     public PersistenceUnitUtil getPersistenceUnitUtil();
 
+    /**
+     * Return interface providing access to schema management
+     * operations for the persistence unit.
+     * @return <code>SchemaManager</code> interface
+     * @throws IllegalStateException if the entity manager factory
+     * has been closed
+     *
+     * @since 3.2
+     */
+    public SchemaManager getSchemaManager();
+
     /**
      * Define the query, typed query, or stored procedure query as
      * a named query such that future query objects can be created

diff --git a/api/src/main/java/jakarta/persistence/SchemaManager.java b/api/src/main/java/jakarta/persistence/SchemaManager.java
@@ -0,0 +1,86 @@
+/*
+ * Copyright (c) 2008, 2021 Oracle and/or its affiliates. All rights reserved.
+ *
+ * This program and the accompanying materials are made available under the
+ * terms of the Eclipse Public License v. 2.0 which is available at
+ * http://www.eclipse.org/legal/epl-2.0,
+ * or the Eclipse Distribution License v. 1.0 which is available at
+ * http://www.eclipse.org/org/documents/edl-v10.php.
+ *
+ * SPDX-License-Identifier: EPL-2.0 OR BSD-3-Clause
+ */
+
+// Contributors:
+//     Gavin King      - 3.2
+
+package jakarta.persistence;
+
+import java.util.Map;
+
+/**
+ * Allows programmatic {@linkplain #create schema creation},
+ * {@linkplain #validate schema validation},
+ * {@linkplain #truncate data cleanup}, and
+ * {@linkplain #drop schema cleanup} for entities belonging
+ * to a certain persistence unit.
+ * 
+ * <p>Properties are inherited from the {@link EntityManagerFactory},
+ * that is, they may be specified via {@code persistence.xml} or
+ * {@link Persistence#createEntityManagerFactory(String, Map)}.
+ *
+ * @see EntityManagerFactory#getSchemaManager()
+ *
+ * @since 3.2
+ */
+public interface SchemaManager {
+	/**
+	 * Create database objects mapped by entities belonging to the
+	 * persistence unit.
+	 *
+	 * @param createSchemas if {@code true}, attempt to create schemas,
+	 *                      otherwise, assume the schemas already exist
+	 *
+	 * @implSpec If a DDL operation fails, the behavior is undefined.
+	 * A provider may throw an exception, or it may ignore the problem
+	 * and continue.
+	 */
+	void create(boolean createSchemas);
+
+	/**
+	 * Drop database objects mapped by entities belonging to the
+	 * persistence unit, undoing the effects of the
+	 * {@linkplain #create(boolean) previous creation}.
+	 *
+	 * <p>If a DDL operation fails, the behavior is undefined.
+	 * A provider may throw an exception, or it may ignore the problem
+	 * and continue.
+	 *
+	 * @param dropSchemas if {@code true}, drop schemas,
+	 *                    otherwise, leave them be
+	 */
+	void drop(boolean dropSchemas);
+
+	/**
+	 * Validate that the database objects mapped by entities belonging
+	 * to the persistence unit have the expected definitions.
+	 *
+	 * <p>The persistence provider is not required to perform
+	 * any specific validation, so the semantics of this operation are
+	 * entirely provider-specific.
+	 *
+	 * @throws PersistenceException if a database object is missing or
+	 * does not have the expected definition
+	 */
+	void validate();
+
+	/**
+	 * Truncate the database tables mapped by entities belonging to
+	 * the persistence unit, and then re-import initial data from any
+	 * configured SQL scripts for data loading.
+	 *
+	 * <p>If a SQL operation fails, the behavior is undefined.
+	 * A provider may throw an exception, or it may ignore the problem
+	 * and continue.
+	 */
+	void truncate();
+}