Chapter 9. Runtime Extensions

; Fri, 6 Jan 2017 19:19:26 +0000 (UTC) Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit Subject: svn commit: r1004302 [40/41] - in /websites/production/openjpa/content/builds/2.4.2: ./ apache-openjpa/ apache-openjpa/docs/ apache-openjpa/docs/css/ apache-openjpa/docs/img/ Date: Fri, 06 Jan 2017 19:19:22 -0000 To: commits@openjpa.apache.org From: ilgrosso@apache.org X-Mailer: svnmailer-1.0.9 Message-Id: <20170106191926.2A33C3A09A1@svn01-us-west.apache.org> archived-at: Fri, 06 Jan 2017 19:19:33 -0000 Added: websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/ref_guide_runtime.html ============================================================================== --- websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/ref_guide_runtime.html (added) +++ websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/ref_guide_runtime.html Fri Jan 6 19:19:20 2017 @@ -0,0 +1,222 @@ + + + Chapter 9. Runtime Extensions

Chapter 9. + Runtime Extensions +
Prev	Part 3. Reference Guide	Next

Chapter 9. + Runtime Extensions +

Table of Contents

1. + Architecture +

1.1. + Broker Finalization +
1.2. + Broker Customization and Eviction +

2. + JPA Extensions +

2.1. + OpenJPAEntityManagerFactory +
2.2. + OpenJPAEntityManager +
2.3. + OpenJPAQuery +
2.4. + Extent +
2.5. + StoreCache +
2.6. + QueryResultCache +
2.7. + FetchPlan +
2.8. + OpenJPAEntityTransaction +
2.9. + OpenJPAPersistence +

3. + Object Locking +

3.1. + Configuring Default Locking +
3.2. + Configuring Lock Levels at Runtime +
3.3. + Object Locking APIs +
3.4. + Lock Manager +
3.5. + Rules for Locking Behavior +
3.6. + Known Issues and Limitations +

4. + Savepoints +

4.1. + Using Savepoints +
4.2. + Configuring Savepoints +

5. + MethodQL +

6. + Generators +

6.1. + Runtime Access +

7. + Transaction Events +

8. + Non-Relational Stores +

+ +

+This chapter describes OpenJPA extensions to the standard JPA +interfaces, and outlines some additional features of the OpenJPA runtime. +

1. + Architecture +

1.1. + Broker Finalization +
1.2. + Broker Customization and Eviction +

+ +

+Internally, OpenJPA does not adhere to any persistence specification. The +OpenJPA kernel has its own set of APIs and components. Specifications like JPA +and JDO are simply different "personalities" that OpenJPA's native kernel +can adopt. +

+As an OpenJPA user, you will not normally see beneath +OpenJPA's JPA personality. OpenJPA allows you to access its feature set without +leaving the comfort of JPA. Where OpenJPA goes beyond standard JPA +functionality, we have crafted JPA-specific APIs to each OpenJPA extension for +as seamless an experience as possible. +

+When writing OpenJPA plugins or otherwise extending the OpenJPA runtime, +however, you will use OpenJPA's native APIs. So that you won't feel lost, the +list below associates each specification interface with its backing native +OpenJPA component: +

+
+javax.persistence.EntityManagerFactory: +org.apache.openjpa.kernel.BrokerFactory +
+
+
+javax.persistence.EntityManager: +org.apache.openjpa.kernel.Broker +
+
+
+javax.persistence.Query: +org.apache.openjpa.kernel.Query +
+
+
+org.apache.openjpa.persistence.Extent: +org.apache.openjpa.kernel.Extent +
+
+
+org.apache.openjpa.persistence.StoreCache: +org.apache.openjpa.datacache.DataCache +
+
+
+org.apache.openjpa.persistence.QueryResultCache: +org.apache.openjpa.datacache.QueryCache + +
+
+
+org.apache.openjpa.persistence.FetchPlan: +org.apache.openjpa.kernel.FetchConfiguration +
+
+
+org.apache.openjpa.persistence.Generator: +org.apache.openjpa.kernel.Seq +
+

+The +org.apache.openjpa.persistence.OpenJPAPersistence helper +allows you to convert between EntityManagerFactories and +BrokerFactories, EntityManagers +and Brokers. +

1.1. + Broker Finalization +

+ + +

+Outside of a Java EE application server or other JPA persistence container +environment, the default OpenJPAEntityManager implementation automatically +closes itself during instance finalization. This guards against accidental +resource leaks that may occur if a developer fails to explicitly close +EntityManagers when finished with them, but it also incurs a scalability +bottleneck, since the JVM must perform synchronization during instance creation, +and since the finalizer thread will have more instances to monitor. To avoid +this overhead, set the +openjpa.BrokerImpl +configuration property to non-finalizing. +

1.2. + Broker Customization and Eviction +

+ + +

+As a plugin string, this property +can be used to configure the BrokerImpl with the +following properties: +

+
+EvictFromDataCache: When evicting an object through the +OpenJPAEntityManager.evict methods, whether to also +evict it from the OpenJPA's data cache. +Defaults to false. +
+

Example 9.1. + Evict from Data Cache +

+ +

+<property name="openjpa.BrokerImpl" value="EvictFromDataCache=true"/>
+

+Additionally, some advanced users may want to add capabilities to OpenJPA's +internal +org.apache.openjpa.kernel.BrokerImpl. You can +configure OpenJPA to use a custom subclass of BrokerImpl +with the openjpa.BrokerImpl + configuration property. Set this property to the full class +name of your custom subclass. When implementing your subclass, consider the +finalization issues mentioned in +Section 1.1, “ + Broker Finalization + ”. It may be appropriate +to create a subtype of both + +org.apache.openjpa.kernel.BrokerImpl and + +org.apache.openjpa.kernel.FinalizingBrokerImpl. +

+ + + + + + + + + +

Prev	Up	Next
3. + XA Transactions +	Home	2. + JPA Extensions +

\ No newline at end of file Added: websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/ref_guide_runtime_jpa.html ============================================================================== --- websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/ref_guide_runtime_jpa.html (added) +++ websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/ref_guide_runtime_jpa.html Fri Jan 6 19:19:20 2017 @@ -0,0 +1,242 @@ + + + 2. JPA Extensions

2. + JPA Extensions +
Prev	Chapter 9. + Runtime Extensions +	Next

2. + JPA Extensions +

2.1. + OpenJPAEntityManagerFactory +
2.2. + OpenJPAEntityManager +
2.3. + OpenJPAQuery +
2.4. + Extent +
2.5. + StoreCache +
2.6. + QueryResultCache +
2.7. + FetchPlan +
2.8. + OpenJPAEntityTransaction +
2.9. + OpenJPAPersistence +

+ +

+The following sections outline the runtime interfaces you can use to access +OpenJPA-specific functionality from JPA. Each interface contains services and +convenience methods missing from the JPA specification. OpenJPA strives to use +the same naming conventions and API patterns as standard JPA methods in all +extensions, so that OpenJPA extension APIs feel as much as possible like +standard JPA. +

+You may have noticed the examples throughout this document using the +OpenJPAPersistence.cast methods to cast from standard +JPA interfaces to OpenJPA extended interfaces. This is the recommended practice. +Some application server vendors may proxy OpenJPA's JPA implementation, +preventing a straight cast. OpenJPAPersistence's +cast methods work around these proxies. +

 
+public static OpenJPAEntityManagerFactory cast(EntityManagerFactory emf);
+public static OpenJPAEntityManager cast(EntityManager em);
+public static OpenJPAQuery cast(Query q);
+

+We provide additional information on the OpenJPAPersistence + helper +below. +

2.1. + OpenJPAEntityManagerFactory +

+ + + +

+The org.apache.openjpa.persistence.OpenJPAEntityManagerFactory + interface extends the basic +javax.persistence.EntityManagerFactory with OpenJPA-specific +features. The OpenJPAEntityManagerFactory offers APIs to +access the OpenJPA data and query caches and to perform other OpenJPA-specific +operations. See the + +interface Javadoc for details. +

2.2. + OpenJPAEntityManager +

+ + + +

+All OpenJPA EntityManagers implement the + +org.apache.openjpa.persistence.OpenJPAEntityManager + interface. This interface extends the standard +javax.persistence.EntityManager. Just as the standard +EntityManager is the primary window into JPA services, the +OpenJPAEntityManager is the primary window from JPA into +OpenJPA-specific functionality. We strongly encourage you to investigate the API +extensions this interface contains. +

2.3. + OpenJPAQuery +

+ + + +

+OpenJPA extends JPA's standard query functionality with the +org.apache.openjpa.persistence.OpenJPAQuery interface. See its +Javadoc + for details on the convenience methods it provides. +

2.4. + Extent +

+ + + +

+An Extent is a logical view of all persistent instances +of a given entity class, possibly including subclasses. OpenJPA adds the ++org.apache.openjpa.persistence.Extent class to the set of +Java Persistence APIs. The following code illustrates iterating over all +instances of the Magazine entity, without subclasses: +

Example 9.2. + Using a JPA Extent +

+ +

+import org.apache.openjpa.persistence.*;
+
+...
+
+OpenJPAEntityManager kem = OpenJPAPersistence.cast(em);
+Extent<Magazine> mags = kem.createExtent(Magazine.class, false);
+for (Magazine m : mags)
+    processMagazine(m);
+

2.5. + StoreCache +

+ + +

+In addition to the EntityManager object cache the JPA +specification provides access to a second level cache via the +javax.persistence.Cache interface. OpenJPA provides further extensions via +the org.apache.openjpa.persistence.StoreCache interface documented at + +org.apache.openjpa.persistence.StoreCache. +Section 1, “ + Data Cache + ” has detailed information on OpenJPA's +data caching system, including the StoreCache facade. +

2.6. + QueryResultCache +

+ + +

+OpenJPA can cache query results as well as persistent object data. The + +org.apache.openjpa.persistence.QueryResultCache +is an JPA-flavored facade to OpenJPA's internal query cache. See +Section 1.4, “ + Query Cache + ” for details on query caching in +OpenJPA. +

2.7. + FetchPlan +

+ + + +

+Many of the aforementioned OpenJPA interfaces give you access to an +org.apache.openjpa.persistence.FetchPlan instance. The +FetchPlan allows you to exercise some control over how objects are +fetched from the datastore, including +large result set support, custom fetch +groups, and lock levels. +

+OpenJPA goes one step further, extending FetchPlan with + +org.apache.openjpa.persistence.jdbc.JDBCFetchPlan +to add additional JDBC-specific tuning methods. Unless you have customized +OpenJPA to use a non-relational back-end (see +Section 8, “ + Non-Relational Stores + ” ), all +FetchPlans in OpenJPA implement +JDBCFetchPlan, so feel free to cast to this interface. +

+Fetch plans pass on from parent components to child components. The +EntityManagerFactory settings (via your configuration properties) +for things like the fetch size, result set type, and custom fetch groups are +passed on to the fetch plan of the EntityManagers it +produces. The settings of each EntityManager, in turn, +are passed on to each Query and Extent + it returns. Note that the opposite, however, is not true. Modifying +the fetch plan of a Query or Extent + does not affect the EntityManager's +configuration. Likewise, modifying an EntityManager's +configuration does not affect the EntityManagerFactory. +

+Section 7, “ + Fetch Groups + ” includes examples using +FetchPlans. +

2.8. + OpenJPAEntityTransaction +

+ + +

+ +org.apache.openjpa.persistence.OpenJPAEntityTransaction +extends javax.persistence.EntityTransaction to provide +additional transaction-debugging capabilities and some concurrency-related +commit and rollback features. +

2.9. + OpenJPAPersistence +

+ + +

+ +org.apache.openjpa.persistence.OpenJPAPersistence +is a static helper class that adds OpenJPA-specific utility methods to +javax.persistence.Persistence. +

Prev	Up	Next
Chapter 9. + Runtime Extensions +	Home	3. + Object Locking +

\ No newline at end of file Added: websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/ref_guide_runtime_pm_event.html ============================================================================== --- websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/ref_guide_runtime_pm_event.html (added) +++ websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/ref_guide_runtime_pm_event.html Fri Jan 6 19:19:20 2017 @@ -0,0 +1,42 @@ + + + 7. Transaction Events

7. + Transaction Events +
Prev	Chapter 9. + Runtime Extensions +	Next

7. + Transaction Events +

+ + +

+The OpenJPA runtime supports broadcasting transaction-related events. By +registering one or more + +org.apache.openjpa.event.TransactionListener s, +you can receive notifications when transactions begin, flush, rollback, commit, +and more. Where appropriate, event notifications include the set of +persistence-capable objects participating in the transaction. +

+public void addTransactionListener(Object listener);
+public void removeTransactionListener(Object listener);
+

+These OpenJPAEntityManagerSPI methods allow you to add +and remove listeners. These methods are outside the bounds of the published OpenJPA APIs, and are subject to change in the future. +

+For details on the transaction framework, see the +org.apache.openjpa.event package +Javadoc. +Also see Section 2, “ + Remote Event Notification Framework + ” for a description of OpenJPA's +remote event support. +

Prev	Up	Next
6. + Generators +	Home	8. + Non-Relational Stores +

\ No newline at end of file Added: websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/ref_guide_savepoints.html ============================================================================== --- websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/ref_guide_savepoints.html (added) +++ websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/ref_guide_savepoints.html Fri Jan 6 19:19:20 2017 @@ -0,0 +1,143 @@ + + + 4. Savepoints

4. + Savepoints +
Prev	Chapter 9. + Runtime Extensions +	Next

4. + Savepoints +

4.1. + Using Savepoints +
4.2. + Configuring Savepoints +

+ + +

+Savepoints allow for fine grained control over the transactional behavior of +your application. OpenJPA's savepoint API allow you to set intermediate rollback +points in your transaction. You can then choose to rollback changes made only +after a specific savepoint, then commit or continue making new changes in the +transaction. This feature is useful for multi-stage transactions, such as +editing a set of objects over several web pages or user screens. Savepoints also +provide more flexibility to conditional transaction behavior, such as choosing to +commit or rollback a portion of the transaction based on the results of the +changes. This chapter describes how to use and configure OpenJPA savepoints. +

4.1. + Using Savepoints +

+ +

+OpenJPA's + +OpenJPAEntityManager have the following +methods to control savepoint behavior. Note that the savepoints work in tandem +with the current transaction. This means that savepoints require an open +transaction, and that a rollback of the transaction will rollback all of the +changes in the transaction regardless of any savepoints set. +

+void setSavepoint(String name);
+void releaseSavepoint(String name);
+void rollbackToSavepoint(String name);
+

+To set a savepoint, simply call setSavepoint, passing +in a symbolic savepoint name. This savepoint will define a point at which you +can preserve the state of transactional objects for the duration of the current +transaction. +

+Having set a named savepoint, you can rollback changes made after that point by +calling rollbackToSavepoint. This method will keep the +current transaction active, while restoring all transactional instances back to +their saved state. Instances that were deleted after the save point will no +longer be marked for deletion. Similarly, transient instances that were made +persistent after the savepoint will become transient again. Savepoints made +after this savepoint will be released and no longer valid, although you can +still set new savepoints. Savepoints will also be cleared after the current +transaction is committed or rolled back. +

+If a savepoint is no longer needed, you can release any resources it is +consuming resources by calling releaseSavepoint. This +method should not be called for savepoints that have been +released automatically through other means, such as commit of a transaction or +rollback to a prior savepoint. While savepoints made after this savepoint will +also be released, there are no other effects on the current transaction. +

+The following simple example illustrates setting, releasing, and rolling back to +a savepoint. +

Example 9.7. + Using Savepoints +

+ +

+import org.apache.openjpa.persistence.*;
+
+...
+
+OpenJPAEntityManager oem = OpenJPAPersistence.cast(em);
+oem.getTransaction().begin();
+
+Magazine mag = oem.find(Magazine.class, id);
+mag.setPageCount(300);
+oem.setSavepoint("pages");
+
+mag.setPrice(mag.getPageCount() * pricePerPage);
+// we decide to release "pages"...
+oem.releaseSavepoint("pages");
+// ... and set a new savepoint which includes all changes
+oem.setSavepoint("price");
+
+mag.setPrice(testPrice);
+// we determine the test price is not good
+oem.rollbackToSavepoint("price");
+// had we chosen to not release "pages", we might have rolled back to
+// "pages" instead
+
+// the price is now restored to mag.getPageCount() * pricePerPage
+oem.getTransaction().commit();
+

4.2. + Configuring Savepoints +

+ +

+OpenJPA uses the + +org.apache.openjpa.kernel.SavepointManager +plugin to handle preserving the +savepoint state. OpenJPA includes the following SavepointManager + plugins: +

+
+in-mem: The default. This is an alias for the ++org.apache.openjpa.kernel.InMemorySavepointManager. This +plugin stores all state, including field values, in memory. Due to this +behavior, each set savepoint is designed for small to medium transactional +object counts. +
+
+
+jdbc: This is an alias for the ++org.apache.openjpa.jdbc.kernel.JDBC3SavepointManager. This +plugin requires JDBC 3 and java.sql.Savepoint + support to operate. Note that this plugin implements savepoints by +issuing a flush to the database. +
+

Prev	Up	Next
3. + Object Locking +	Home	5. + MethodQL +

\ No newline at end of file Added: websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/ref_guide_schema_def.html ============================================================================== --- websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/ref_guide_schema_def.html (added) +++ websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/ref_guide_schema_def.html Fri Jan 6 19:19:20 2017 @@ -0,0 +1,47 @@ + + + 11. Default Schema

11. + Default Schema +
Prev	Chapter 4. + JDBC +	Next

11. + Default Schema +

+ + +

+It is common to duplicate a database model in multiple schemas. You may have one +schema for development and another for production, or different database users +may access different schemas. OpenJPA facilitates these patterns with the +openjpa.jdbc.Schema + configuration property. This property establishes a default schema for +any unqualified table names, allowing you to leave schema names out of your +mapping definitions. +

+The Schema property also establishes the default schema for +new tables created through OpenJPA tools, such as the mapping tool covered in +Section 1, “ + Forward Mapping + ”. +

+If the entities are mapped to the same table name but with different schema +name within one PersistenceUnit intentionally, and the +strategy of GeneratedType.AUTO is used to generate the ID +for each entity, a schema name for each entity must be explicitly declared +either through the annotation or the mapping.xml file. Otherwise, the mapping +tool only creates the tables for those entities with the schema names under +each schema. In addition, there will be only one +OPENJPA_SEQUENCE_TABLE created for all the entities within +the PersistenceUnit if the entities are not identified +with the schema name. +Read Section 6, “ + Generators + ” in the Reference Guide. +

Prev	Up	Next
10. + Large Result Sets +	Home	12. + Schema Reflection +

\ No newline at end of file Added: websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/ref_guide_schema_info.html ============================================================================== --- websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/ref_guide_schema_info.html (added) +++ websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/ref_guide_schema_info.html Fri Jan 6 19:19:20 2017 @@ -0,0 +1,162 @@ + + + 12. Schema Reflection

12. + Schema Reflection +
Prev	Chapter 4. + JDBC +	Next

12. + Schema Reflection +

12.1. + Schemas List +
12.2. + Schema Factory +

+ + +

+OpenJPA needs information about your database schema for two reasons. First, it +can use schema information at runtime to validate that your schema is compatible +with your persistent class definitions. Second, OpenJPA requires schema +information during development so that it can manipulate the schema to match +your object model. OpenJPA uses the SchemaFactory interface +to provide runtime mapping information, and the SchemaTool + for development-time data. Each is presented below. +

12.1. + Schemas List +

+ + + +

+By default, schema reflection acts on all the schemas your JDBC driver can +"see". You can limit the schemas and tables OpenJPA acts on with the +openjpa.jdbc.Schemas configuration property. This property accepts a +comma-separated list of schemas and tables. To list a schema, list its name. To +list a table, list its full name in the form +<schema-name>.<table-name>. If a table does not have a +schema or you do not know its schema, list its name as +.<table-name> (notice the preceding '.'). For example, to list +the BUSOBJS schema, the ADDRESS table in +the GENERAL schema, and the SYSTEM_INFO +table, regardless of what schema it is in, use the string: +

+BUSOBJS,GENERAL.ADDRESS,.SYSTEM_INFO
+

Note

+Some databases are case-sensitive with respect to schema and table names. +Oracle, for example, requires names in all upper case. +

12.2. + Schema Factory +

+ + +

+OpenJPA relies on the + +openjpa.jdbc.SchemaFactory interface for runtime +schema information. You can control the schema factory OpenJPA uses through the +openjpa.jdbc.SchemaFactory property. There are several +built-in options to choose from: +

+
+dynamic: This is the default setting. It is an alias for the + ++org.apache.openjpa.jdbc.schema.DynamicSchemaFactory. The +DynamicSchemaFactory is the most performant +schema factory, because it does not validate mapping information against the +database. Instead, it assumes all object-relational mapping information is +correct, and dynamically builds an in-memory representation of the schema from +your mapping metadata. When using this factory, it is important that your +mapping metadata correctly represent your database's foreign key constraints so +that OpenJPA can order its SQL statements to meet them. +
+
+
+native: This is an alias for the + +org.apache.openjpa.jdbc.schema.LazySchemaFactory +. As persistent classes are loaded by the application, OpenJPA reads their +metadata and object-relational mapping information. This factory uses the +java.sql.DatabaseMetaData interface to reflect on the +schema and ensure that it is consistent with the mapping data being read. +Use this factory if you want up-front validation that your mapping metadata is +consistent with the database during development. This factory accepts the +following important properties: +
+
- +
  +ForeignKeys: Set to true to automatically +read foreign key information during schema validation. +
  +
+
+
+table: This is an alias for the + +org.apache.openjpa.jdbc.schema.TableSchemaFactory +. This schema factory stores schema information as an XML document in a database +table it creates for this purpose. If your JDBC driver doesn't support the +java.sql.DatabaseMetaData standard interface, but you +still want some schema validation to occur at runtime, you might use this +factory. It is not recommended for most users, though, because it is easy for +the stored XML schema definition to get out-of-synch with the actual database. +This factory accepts the following properties: +
+
- +
  +Table: The name of the table to create to store schema +information. Defaults to OPENJPA_SCHEMA. +
  +
- +
  +PrimaryKeyColumn: The name of the table's numeric primary +key column. Defaults to ID. +
  +
- +
  +SchemaColumn: The name of the table's string column for +holding the schema definition as an XML string. Defaults to SCHEMA_DEF +. +
  +
+
+
+file: This is an alias for the + +org.apache.openjpa.jdbc.schema.FileSchemaFactory +. This factory is a lot like the TableSchemaFactory, and +has the same advantages and disadvantages. Instead of storing its XML schema +definition in a database table, though, it stores it in a file. This factory +accepts the following properties: +
+
- +
  +File: The resource name of the XML schema file. By default, +the factory looks for a resource called package.schema, +located in any top-level directory of the CLASSPATH or in the +top level of any jar in your CLASSPATH. +
  +
+

+You can switch freely between schema factories at any time. The XML file format +used by some factories is detailed in Section 14, “ + XML Schema Format + ” +. As with any OpenJPA plugin, you can also implement your own schema +factory if you have needs not met by the existing options. +

Prev	Up	Next
11. + Default Schema +	Home	13. + Schema Tool +

\ No newline at end of file Added: websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/ref_guide_schema_schematool.html ============================================================================== --- websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/ref_guide_schema_schematool.html (added) +++ websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/ref_guide_schema_schematool.html Fri Jan 6 19:19:20 2017 @@ -0,0 +1,281 @@ + + + 13. Schema Tool

13. + Schema Tool +
Prev	Chapter 4. + JDBC +	Next

13. + Schema Tool +

+ + + + + +

+Most users will only access the schema tool indirectly, through the interfaces +provided by other tools. You may find, however, that the schema tool is a +powerful utility in its own right. The schema tool has two functions: +

+
+To reflect on the current database schema, optionally translating it to an XML +representation for further manipulation. +
+
+
+To take in an XML schema definition, calculate the differences between the XML +and the existing database schema, and apply the necessary changes to make the +database match the XML. +
+

+The XML format used by the schema +tool abstracts away the differences between SQL dialects used by different +database vendors. The tool also automatically adapts its SQL to meet foreign key +dependencies. Thus the schema tool is useful as a general way to manipulate +schemas. +

+You can invoke the schema tool through its Java class, + +org.apache.openjpa.jdbc.schema.SchemaTool. In +addition to the universal flags of the +configuration framework, the schema tool accepts the following command +line arguments: +

+
+-ignoreErrors/-i <true/t | false/f>: If false +, an exception will be thrown if the tool encounters any database +errors. Defaults to false. +
+
+
+-file/-f <stdout | output file>: Use this option to +write a SQL script for the planned schema modifications, rather them committing +them to the database. When used in conjunction with the export + or reflect actions, the named file will be used to +write the exported schema XML. If the file names a resource in the +CLASSPATH, data will be written to that resource. Use stdout + to write to standard output. Defaults to stdout. +
+
+
+-openjpaTables/-ot <true/t | false/f>: When reflecting +on the schema, whether to reflect on tables and sequences whose names start with +OPENJPA_. Certain OpenJPA components may use such tables - +for example, the table schema factory option covered in +Section 12.2, “ + Schema Factory + ”. When using other +actions, openjpaTables controls whether these tables can be +dropped. Defaults to false. +
+
+
+-dropTables/-dt <true/t | false/f>: Set this option to +true to drop tables that appear to be unused during +retain and refresh actions. Defaults to +true. +
+
+
+-dropSequences/-dsq <true/t | false/f>: Set this +option to true to drop sequences that appear to be unused +during retain and refresh actions. +Defaults to true. +
+
+
+-sequences/-sq <true/t | false/f>: Whether to +manipulate sequences. Defaults to true. +
+
+
+-indexes/-ix <true/t | false/f>: Whether to manipulate +indexes on existing tables. Defaults to true. +
+
+
+-primaryKeys/-pk <true/t | false/f>: Whether to +manipulate primary keys on existing tables. Defaults to true. +
+
+
+-foreignKeys/-fk <true/t | false/f>: Whether to +manipulate foreign keys on existing tables. Defaults to true. +
+
+
+-record/-r <true/t | false/f>: Use false + to prevent writing the schema changes made by the tool to the current +schema +factory. Defaults to true. +
+
+
+-schemas/-s <schema list>: A list of schema and table +names that OpenJPA should access during this run of the schema tool. This is +equivalent to setting the +openjpa.jdbc.Schemas property for a single run. +
+

+The schema tool also accepts an -action or -a + flag. Multiple actions can be composed in a comma-separated list. +The available actions are: +

+
+add: This is the default action if you do not specify one. +It brings the schema up-to-date with the given XML document by adding tables, +columns, indexes, etc. This action never drops any schema components. +
+
+
+retain: Keep all schema components in the given XML +definition, but drop the rest from the database. This action never adds any +schema components. +
+
+
+drop: Drop all schema components in the schema XML. Tables +will only be dropped if they would have 0 columns after dropping all columns +listed in the XML. +
+
+
+refresh: Equivalent to retain, then +add. +
+
+
+build: Generate SQL to build a schema matching the one in +the given XML file. Unlike add, this option does not take +into account the fact that part of the schema defined in the XML file might +already exist in the database. Therefore, this action is typically used in +conjunction with the -file flag to write a SQL script. This +script can later be used to recreate the schema in the XML. +
+
+
+reflect: Generate an XML representation of the current +database schema. +
+
+
+createDB: Generate SQL to re-create the current database. +This action is typically used in conjunction with the -file +flag to write a SQL script that can be used to recreate the current schema on a +fresh database. +
+
+
+dropDB: Generate SQL to drop the current database. Like +createDB, this action can be used with the -file + flag to script a database drop rather than perform it. +
+
+
+import: Import the given XML schema definition into the +current schema factory. Does nothing if the factory does not store a record of +the schema. +
+
+
+export: Export the current schema factory's stored schema +definition to XML. May produce an empty file if the factory does not store a +record of the schema. +
+
+
+deleteTableContents: Execute SQL to delete all rows from +all tables that OpenJPA knows about. +
+

Note

+The schema tool manipulates tables, columns, indexes, constraints, and +sequences. It cannot create or drop the database schema objects in which the +tables reside, however. If your XML documents refer to named database schemas, +those schemas must exist. +

+We present some examples of schema tool usage below. +

Example 4.18. + Schema Creation +

+ + +

+Add the necessary schema components to the database to match the given XML +document, but don't drop any data: +

+java org.apache.openjpa.jdbc.schema.SchemaTool targetSchema.xml
+

Example 4.19. + SQL Scripting +

+ +

+Repeat the same action as the first example, but this time don't change the +database. Instead, write any planned changes to a SQL script: +

+java org.apache.openjpa.jdbc.schema.SchemaTool -f script.sql targetSchema.xml
+

+Write a SQL script that will re-create the current database: +

+java org.apache.openjpa.jdbc.schema.SchemaTool -a createDB -f script.sql
+

Example 4.20. + Table Cleanup +

+ + + +

+Refresh the schema and delete all contents of all tables that OpenJPA +knows about: +

+java org.apache.openjpa.jdbc.schema.SchemaTool -a refresh,deleteTableContents
+

Example 4.21. + Schema Drop +

+ +

+Drop the current database: +

+java org.apache.openjpa.jdbc.schema.SchemaTool -a dropDB
+

Example 4.22. + Schema Reflection +

+ + +

+Write an XML representation of the current schema to file schema.xml +. +

+java org.apache.openjpa.jdbc.schema.SchemaTool -a reflect -f schema.xml
+

Prev	Up	Next
12. + Schema Reflection +	Home	14. + XML Schema Format +

\ No newline at end of file Added: websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/ref_guide_schema_xml.html ============================================================================== --- websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/ref_guide_schema_xml.html (added) +++ websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/ref_guide_schema_xml.html Fri Jan 6 19:19:20 2017 @@ -0,0 +1,163 @@ + + + 14. XML Schema Format

14. + XML Schema Format +
Prev	Chapter 4. + JDBC +	Next

14. + XML Schema Format +

+ + +

+The schema tool and + schema factories all use +the same XML format to represent database schema. The Document Type Definition +(DTD) for schema information is presented below, followed by examples of schema +definitions in XML. +

+<!ELEMENT schemas (schema)+>
+<!ELEMENT schema (table|sequence)+>
+<!ATTLIST schema name CDATA #IMPLIED>
+
+<!ELEMENT sequence EMPTY>
+<!ATTLIST sequence name CDATA #REQUIRED>
+<!ATTLIST sequence initial-value CDATA #IMPLIED>
+<!ATTLIST sequence increment CDATA #IMPLIED>
+<!ATTLIST sequence allocate CDATA #IMPLIED>
+
+<!ELEMENT table (column|index|pk|fk|unique)+>
+<!ATTLIST table name CDATA #REQUIRED>
+
+<!ELEMENT column EMPTY>
+<!ATTLIST column name CDATA #REQUIRED> 
+<!ATTLIST column type (array | bigint | binary | bit | blob | char | clob 
+    | date | decimal | distinct | double | float | integer | java_object 
+    | longvarbinary | longvarchar | null | numeric | other | real | ref 
+    | smallint | struct | time | timestamp | tinyint | varbinary | varchar) 
+    #REQUIRED>
+<!ATTLIST column not-null (true|false) "false">
+<!ATTLIST column auto-assign (true|false) "false">
+<!ATTLIST column default CDATA #IMPLIED>
+<!ATTLIST column size CDATA #IMPLIED>
+<!ATTLIST column decimal-digits CDATA #IMPLIED>
+
+<!-- the type-name attribute can be used when you want OpenJPA to   -->
+<!-- use a particular SQL type declaration when creating the     -->
+<!-- column. It is up to you to ensure that this type is         -->
+<!-- compatible with the JDBC type used in the type attribute.   -->
+<!ATTLIST column type-name CDATA #IMPLIED>
+
+<!-- the 'column' attribute of indexes, pks, and fks can be used -->
+<!-- when the element has only one column (or for foreign keys,  -->
+<!-- only one local column); in these cases the on/join child    -->
+<!-- elements can be omitted                                     -->
+<!ELEMENT index (on)*>
+<!ATTLIST index name CDATA #REQUIRED>
+<!ATTLIST index column CDATA #IMPLIED>
+<!ATTLIST index unique (true|false) "false">
+
+<!-- the 'logical' attribute of pks should be set to 'true' if   --> 
+<!-- the primary key does not actually exist in the database,    --> 
+<!-- but the given column should be used as a primary key for    -->
+<!-- O-R purposes                                                -->
+<!ELEMENT pk (on)*>
+<!ATTLIST pk name CDATA #IMPLIED>
+<!ATTLIST pk column CDATA #IMPLIED>
+<!ATTLIST pk logical (true|false) "false">
+
+<!ELEMENT on EMPTY>
+<!ATTLIST on column CDATA #REQUIRED>
+
+<!-- fks with a delete-action of 'none' are similar to logical   -->
+<!-- pks; they do not actually exist in the database, but        -->
+<!-- represent a logical relation between tables (or their       -->
+<!-- corresponding Java classes)                                 -->
+<!ELEMENT fk (join)*>
+<!ATTLIST fk name CDATA #IMPLIED>
+<!ATTLIST fk deferred (true|false) "false">
+<!ATTLIST fk to-table CDATA #REQUIRED>
+<!ATTLIST fk column CDATA #IMPLIED>
+<!ATTLIST fk delete-action (cascade|default|exception|none|null) "none">
+
+<!ELEMENT join EMPTY>
+<!ATTLIST join column CDATA #REQUIRED>
+<!ATTLIST join to-column CDATA #REQUIRED>
+<!ATTLIST join value CDATA #IMPLIED>
+
+<!-- unique constraint -->
+<!ELEMENT unique (on)*>
+<!ATTLIST unique name CDATA #IMPLIED>
+<!ATTLIST unique column CDATA #IMPLIED>
+<!ATTLIST unique deferred (true|false) "false">
+

Example 4.23. + Basic Schema +

+ +

+A very basic schema definition. +

+<schemas>
+    <schema>
+        <sequence name="S_ARTS"/>
+        <table name="ARTICLE">
+            <column name="TITLE" type="varchar" size="255" not-null="true"/>
+            <column name="AUTHOR_FNAME" type="varchar" size="28"> 
+            <column name="AUTHOR_LNAME" type="varchar" size="28"> 
+            <column name="CONTENT" type="clob"> 
+        </table>
+        <table name="AUTHOR">
+            <column name="FIRST_NAME" type="varchar" size="28" not-null="true"> 
+            <column name="LAST_NAME" type="varchar" size="28" not-null="true"> 
+        </table>
+    </schema>
+</schemas>
+

Example 4.24. + Full Schema +

+ +

+Expansion of the above schema with primary keys, constraints, and indexes, some +of which span multiple columns. +

+<schemas>
+    <schema>
+        <sequence name="S_ARTS"/>
+        <table name="ARTICLE">
+            <column name="TITLE" type="varchar" size="255" not-null="true"/>
+            <column name="AUTHOR_FNAME" type="varchar" size="28"> 
+            <column name="AUTHOR_LNAME" type="varchar" size="28"> 
+            <column name="CONTENT" type="clob"> 
+            <pk column="TITLE"/>
+            <fk to-table="AUTHOR" delete-action="exception">
+                <join column="AUTHOR_FNAME" to-column="FIRST_NAME"/>
+                <join column="AUTHOR_LNAME" to-column="LAST_NAME"/>
+            </fk>
+            <index name="ARTICLE_AUTHOR">
+                <on column="AUTHOR_FNAME"/>
+                <on column="AUTHOR_LNAME"/>
+            </index>
+        </table>
+        <table name="AUTHOR">
+            <column name="FIRST_NAME" type="varchar" size="28" not-null="true"> 
+            <column name="LAST_NAME" type="varchar" size="28" not-null="true"> 
+            <pk>
+                <on column="FIRST_NAME"/>
+                <on column="LAST_NAME"/>
+            </pk>
+        </table>
+    </schema>
+</schemas>
+

Prev	Up	Next
13. + Schema Tool +	Home	Chapter 5. + Persistent Classes +

\ No newline at end of file