Added: websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_runtime.html ============================================================================== --- websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_runtime.html (added) +++ websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_runtime.html Wed May 14 22:22:23 2014 @@ -0,0 +1,222 @@ + + + Chapter 9.  Runtime Extensions

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 +

+ +

+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. +

+
+
+ + + + + + + + + +
\ No newline at end of file Propchange: websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_runtime.html ------------------------------------------------------------------------------ svn:mime-type = text/plain Added: websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_runtime_jpa.html ============================================================================== --- websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_runtime_jpa.html (added) +++ websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_runtime_jpa.html Wed May 14 22:22:23 2014 @@ -0,0 +1,242 @@ + + + 2.  JPA Extensions

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. +

+
+
\ No newline at end of file Propchange: websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_runtime_jpa.html ------------------------------------------------------------------------------ svn:mime-type = text/plain Added: websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_runtime_pm_event.html ============================================================================== --- websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_runtime_pm_event.html (added) +++ websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_runtime_pm_event.html Wed May 14 22:22:23 2014 @@ -0,0 +1,42 @@ + + + 7.  Transaction Events

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. +

+
\ No newline at end of file Propchange: websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_runtime_pm_event.html ------------------------------------------------------------------------------ svn:mime-type = text/plain Added: websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_savepoints.html ============================================================================== --- websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_savepoints.html (added) +++ websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_savepoints.html Wed May 14 22:22:23 2014 @@ -0,0 +1,143 @@ + + + 4.  Savepoints

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: +

+
+
+
\ No newline at end of file Propchange: websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_savepoints.html ------------------------------------------------------------------------------ svn:mime-type = text/plain Added: websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_schema_def.html ============================================================================== --- websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_schema_def.html (added) +++ websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_schema_def.html Wed May 14 22:22:23 2014 @@ -0,0 +1,47 @@ + + + 11.  Default Schema

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. +

+
\ No newline at end of file Propchange: websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_schema_def.html ------------------------------------------------------------------------------ svn:mime-type = text/plain Added: websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_schema_info.html ============================================================================== --- websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_schema_info.html (added) +++ websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_schema_info.html Wed May 14 22:22:23 2014 @@ -0,0 +1,162 @@ + + + 12.  Schema Reflection

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. +

+
+
\ No newline at end of file Propchange: websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_schema_info.html ------------------------------------------------------------------------------ svn:mime-type = text/plain Added: websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_schema_schematool.html ============================================================================== --- websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_schema_schematool.html (added) +++ websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_schema_schematool.html Wed May 14 22:22:23 2014 @@ -0,0 +1,281 @@ + + + 13.  Schema Tool

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: +

+
  1. +

    +To reflect on the current database schema, optionally translating it to an XML +representation for further manipulation. +

    +
  2. +

    +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: +

+
+

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

+
+

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
+
+

+
\ No newline at end of file Propchange: websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_schema_schematool.html ------------------------------------------------------------------------------ svn:mime-type = text/plain Added: websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_schema_xml.html ============================================================================== --- websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_schema_xml.html (added) +++ websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_schema_xml.html Wed May 14 22:22:23 2014 @@ -0,0 +1,163 @@ + + + 14.  XML Schema Format

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>
+
+

+
\ No newline at end of file Propchange: websites/production/openjpa/content/builds/2.3.0/apache-openjpa/docs/ref_guide_schema_xml.html ------------------------------------------------------------------------------ svn:mime-type = text/plain