Added: websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/ref_guide_sequence.html ============================================================================== --- websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/ref_guide_sequence.html (added) +++ websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/ref_guide_sequence.html Fri Jan 6 19:19:20 2017 @@ -0,0 +1,296 @@ + + + 6.  Generators

6.  + Generators +

6.1. + Runtime Access +
+ + +

+The JPA Overview's Chapter 13, + Mapping Metadata + details using +generators to automatically populate identity fields in JPA. +

+

+OpenJPA represents all generators internally with the + +org.apache.openjpa.kernel.Seq interface. This interface +supplies all the context you need to create your own custom generators, +including the current persistence environment, the JDBC DataSource +, and other essentials. The + +org.apache.openjpa.jdbc.kernel.AbstractJDBCSeq +helps you create custom JDBC-based sequences. OpenJPA also supplies the +following built-in Seqs: +

+
+

+You can use JPA SequenceGenerators to describe any built-in +Seqs or your own Seq +implementation. Set the sequenceName attribute to a plugin +string describing your choice. +

+ +
+

+If specifying your own class name, you must include parentheses at the end of +the class name, even if you have no plugin properties to configure. +(E.g., sequenceName="com.example.SeqImpl()". +

+
+ +

+See Section 5, “ + Generators + ” in the JPA Overview for +details on defining SequenceGenerators. +

+ +

+See Section 4, “ + Plugin Configuration + ” for plugin string formatting. +

+

Example 9.8.  + Named Seq Sequence +

+ +
+@Entity
+@Table(name="AUTO")
+public class Author {
+
+    @Id
+    @GeneratedValue(strategy=GenerationType.SEQUENCE, generator="AuthorSeq")
+    @SequenceGenerator(name="AuthorSeq", sequenceName="table(Table=AUTO_SEQ)", allocationSize=100)
+    @Column(name="AID")
+    private long id;
+ 
+    ...
+}
+
+

+Note that if you want to use a plugin string without any arguments, you must +still suffix the plugin type with () to differentiate it from +a sequence name in the SequenceGenerator.sequenceName attribute: +

+
+@SequenceGenerator(name="AuthorSeq", sequenceName="table()")
+
+

+

+ +OpenJPA maintains a system sequence to generate datastore +identity values for classes that do not declare a specific datastore identity +strategy. You can configure the system sequence through the +openjpa.Sequence +configuration property. This property accepts a plugin string describing a +Seq instance. +

+

Example 9.9.  + System Sequence Configuration +

+ +
+<property name="openjpa.Sequence" value="time(Increment=100)"/>
+
+

+

+In JPA, set your GeneratedValue annotation's +strategy attribute to AUTO to use the configured +system sequence. Or, because AUTO is the default strategy, +use the annotation without attributes: +

+
+@GeneratedValue
+private long id;
+
+

6.1.  + Runtime Access +

+ + +

+OpenJPA allows you to access named generators at runtime through the +OpenJPAEntityManager.getNamedGenerator method: +

+
+public Generator getNamedGenerator(String name);
+
+

+The returned + +org.apache.openjpa.persistence.Generator is a +facade over an internal OpenJPA Seq. +

+

+The OpenJPAEntityManager includes additional APIs to +retrieve the identity generator of any class, or the generator of any field. +With these APIs, you do not have to know the generator name. Additionally, they +allow you to access the implicit generator used by default for datastore +identity classes. See the + +Javadoc for the OpenJPAEntityManager.getIdentityGenerator + and OpenJPAEntityManager.getFieldGenerator + methods for API details. +

+
+
\ No newline at end of file Added: websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/ref_guide_slice.html ============================================================================== --- websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/ref_guide_slice.html (added) +++ websites/production/openjpa/content/builds/2.4.2/apache-openjpa/docs/ref_guide_slice.html Fri Jan 6 19:19:20 2017 @@ -0,0 +1,50 @@ + + + Chapter 13.  Slice: Distributed Persistence

Chapter 13.  + Slice: Distributed Persistence +

Table of Contents

1. Overview
2. Salient Features
2.1. Transparency
2.2. Scaling
2.3. Distributed Query
2.4. Data Distribution
2.5. Data Replication
2.6. Heterogeneous Database
2.7. Distributed Transaction
2.8. Collocation Constraint
3. Usage
3.1. How to activate Slice Runtime?
3.2. How to configure each database slice?
3.3. Implement DistributionPolicy interface
3.4. Implement ReplicationPolicy interface
4. Configuration Properties
4.1. Global Properties
4.1.1. openjpa.slice.DistributionPolicy
4.1.2. openjpa.slice.Lenient
4.1.3. openjpa.slice.Master
4.1.4. openjpa.slice.Names
4.1.5. openjpa.slice.ThreadingPolicy
4.1.6. openjpa.slice.TransactionPolicy
4.2. Per-Slice Properties
+ +

+ The standard JPA runtime environment works with a single + database instance. Slice is a plug-in module for OpenJPA + to work with multiple databases within the same + transaction. Following sections describe the features and usage of Slice for + distributed database environment. +

+ +

1. Overview

+ +

+ Enterprise applications are increasingly deployed in distributed database + environment. A distributed, horizontally-partitioned + database environment can be an effective scaling strategy for growing data + volume, to support multiple clients on a multi-tenant hosting platform and + many other practical scenarios that can benefit from data partitioning. +

+ +

+ Any JPA-based user application has to address demanding technical and + conceptual challenges to interact with multiple physical databases + within a single transaction. + OpenJPA Slice encapsulates the complexity of distributed database environment + via the abstraction of virtual database which internally + manages multiple physical database instances referred + as slice. + Virtualization of distributed databases makes OpenJPA + object management kernel and the user application to work in the same way as + in the case of a single physical database. +

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

3. Usage

3.1. How to activate Slice Runtime?
3.2. How to configure each database slice?
3.3. Implement DistributionPolicy interface
3.4. Implement ReplicationPolicy interface
+ +

+ Slice is activated via the following property settings: +

+

3.1. How to activate Slice Runtime?

+ +

+ The basic configuration property is +

 
+         <property name="openjpa.BrokerFactory" value="slice"/>
+       

+ This critical configuration activates a specialized object management + kernel that can work against multiple databases. +

+
+ +

3.2. How to configure each database slice?

+ +

+ Each database slice is identified by a logical name unique within a + persistent unit. The list of the slices is specified by + openjpa.slice.Names property. + For example, specify three slices named "One", + "Two" and "Three" as follows: +

+       <property name="openjpa.slice.Names" value="One, Two, Three"/>
+      

+

+

+ This property is not mandatory. If this property is not specified then + the configuration is scanned for logical slice names. Any property + "abc" of the form openjpa.slice.XYZ.abc will + register a slice with logical + name "XYZ". +

+

+ The order of the names is significant when no openjpa.slice.Master + property is not specified. The persistence unit is then scanned to find + all configured slice names and they are ordered alphabetically. +

+ +

+ Each database slice properties can be configured independently. + For example, the + following configuration will register two slices with logical name + One and Two. +

 
+        <property name="openjpa.slice.One.ConnectionURL" value="jdbc:mysql:localhost//slice1"/>
+        <property name="openjpa.slice.Two.ConnectionURL" value="jdbc:mysql:localhost//slice2"/>
+       

+

+ +

+ Any OpenJPA specific property can be configured per slice basis. + For example, the following configuration will use two different JDBC + drivers for slice One and Two. +

 
+        <property name="openjpa.slice.One.ConnectionDriverName" value="com.mysql.jdbc.Driver"/>
+        <property name="openjpa.slice.Two.ConnectionDriverName" value="com.mysql.jdbc.jdbc2.optional.MysqlXADataSource"/>
+       

+

+ +

+ Any property if unspecified for a particular slice will be defaulted by + corresponding OpenJPA property. For example, consider following three slices +

 
+         <property name="openjpa.slice.One.ConnectionURL"          value="jdbc:mysql:localhost//slice1"/>
+         <property name="openjpa.slice.Two.ConnectionURL"          value="jdbc:mysql:localhost//slice2"/>
+         <property name="openjpa.slice.Three.ConnectionURL"        value="jdbc:oracle:localhost//slice3"/>
+
+         <property name="openjpa.ConnectionDriverName"     value="com.mysql.jdbc.Driver"/>
+         <property name="openjpa.slice.Three.ConnectionDriverName" value="oracle.jdbc.Driver"/>
+        

+ In this example, Three will use slice-specific + oracle.jdbc.Driver driver while slice + One and Two will use + the driver com.mysql.jdbc.Driver as + specified by openjpa.ConnectionDriverName + property value. +

+ +

+ A connection pool may also be used with Slice by using the openjpa.ConnectionProperties property. + For example to use commons-dbcp with Derby you might use the following properties : +

 
+                <property name="openjpa.BrokerFactory" value="slice"/>
+                <property name="openjpa.ConnectionDriverName" value="org.apache.commons.dbcp.BasicDataSource"/>
+                <property name="openjpa.slice.Names" value="One,Two"/>
+                <property name="openjpa.slice.Master" value="Two"/>
+ 
+                <property name="openjpa.slice.One.ConnectionProperties" value="Url=jdbc:derby:target/database/openjpa-slice1;create=true, DriverClassName=org.apache.derby.jdbc.EmbeddedDriver"/>
+                <property name="openjpa.slice.Two.ConnectionProperties" value="Url=jdbc:derby:target/database/openjpa-slice2;create=true, DriverClassName=org.apache.derby.jdbc.EmbeddedDriver"/>
+ 
+                <property name="openjpa.jdbc.DBDictionary" value="derby"/>
+            

+

Note

+

+ Be aware that you need to set the DBDictionary when using commons-dbcp. +

+

+

+
+ +

3.3. Implement DistributionPolicy interface

+ +

+ Slice needs to determine which slice will persist a new instance. + The application can only decide this policy (for example, + all PurchaseOrders before April 30 goes to slice One, + all the rest goes to slice Two). This is why + the application has to implement + org.apache.openjpa.slice.DistributionPolicy and + specify the implementation class in configuration +

 
+          <property name="openjpa.slice.DistributionPolicy" value="com.acme.foo.MyOptimialDistributionPolicy"/>
+        

+

+ +

+ The interface org.apache.openjpa.slice.DistributionPolicy + is simple with a single method. The complete listing of the + documented interface follows: +

 
+        
+public interface DistributionPolicy {
+    /**
+     * Gets the name of the slice where a given instance will be stored.
+     *  
+     * @param pc The newly persistent or to-be-merged object. 
+     * @param slices name of the configured slices.
+     * @param context persistence context managing the given instance.
+     * 
+     * @return identifier of the slice. This name must match one of the
+     * configured slice names. 
+     * @see DistributedConfiguration#getSliceNames()
+     */
+    String distribute(Object pc, List<String> slices, Object context);
+}
+
+       

+

+ +

+ While implementing a distribution policy the most important thing to + remember is collocation constraint. + Because Slice can not establish or query any cross-database relationship, all the + related instances must be stored in the same database slice. + + Slice can determine the closure of a root object by traversal of + cascaded relationships. Hence user-defined policy has to only decide the + database for the root instance that is the explicit argument to + EntityManager.persist() call. + Slice will ensure that all other related instances that get persisted by cascade + are assigned to the same database slice as that of the root instance. + However, the user-defined distribution policy must return the + same slice identifier for the instances that are logically related but + not cascaded for persist. +

+
+ +

3.4. Implement ReplicationPolicy interface

+ +

+ The entities that are enumerated in openjpa.slice.ReplicatedTypes + property can be stored in multiple slices as identical copies. + Specify the implementation class of ReplicationPolicy in configuration as +

 
+          <property name="openjpa.slice.ReplicationPolicy" value="com.acme.foo.MyReplicationPolicy"/>
+        

+

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

Appendix 2.  + Supported Databases +

Table of Contents

1. + Overview +
2. + Verified Database Matrix +
3. + Compatible Database Matrix +
4. + Unverified Database Matrix +
5. + Apache Derby +
6. + Borland Interbase +
6.1. + Known issues with Interbase +
7. + JDataStore +
8. + IBM DB2 +
8.1. + Known issues with DB2 +
9. + Empress +
9.1. + Known issues with Empress +
10. + H2 Database Engine +
10.1. + Known issues with H2 Database Engine +
11. + Hypersonic +
11.1. + Known issues with Hypersonic +
12. + Firebird +
12.1. + Known issues with Firebird +
13. + Informix +
13.1. + Known issues with Informix +
14. + Ingres Database +
14.1. + Known issues with Ingres +
15. + InterSystems Cache +
15.1. + Known issues with InterSystems Cache +
16. + Microsoft Access +
16.1. + Known issues with Microsoft Access +
17. + Microsoft SQL Server +
17.1. + Known issues with SQL Server +
18. + Microsoft FoxPro +
18.1. + Known issues with Microsoft FoxPro +
19. + MySQL +
19.1. + Using Query Hints with MySQL +
19.2. + Known issues with MySQL +
20. + Oracle +
20.1. + Using Query Hints with Oracle +
20.2. + Known issues with Oracle +
21. + Pointbase +
21.1. + Known issues with Pointbase +
22. + PostgreSQL +
22.1. + Known issues with PostgreSQL +
23. + IBM solidDB +
23.1. + M-type tables vs. D-type tables +
23.2. + Concurrency control mechanism +
24. + Sybase Adaptive Server +
24.1. + Known issues with Sybase +
+ + +

1.  + Overview +

+ +

+The following appendix covers the database and JDBC driver versions that are +known to work with OpenJPA, along with any database specific configuration +parameters, known issues or limitations. +The Verified Database Matrix, contains the +list of databases and drivers that were tested extensively against this +release of OpenJPA, while the Compatible Database +Matrix contains the list of databases and drivers that were tested +against prior releases or by OpenJPA users and may not support every feature +of this release. + +The Unverified Database Matrix contains a +list of databases which have been reported to work, but have not been tested by +the development team. +

+
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + +
\ No newline at end of file