Added: websites/production/openjpa/content/builds/2.4.0/apache-openjpa/docs/ref_guide_enterprise_methodql.html ============================================================================== --- websites/production/openjpa/content/builds/2.4.0/apache-openjpa/docs/ref_guide_enterprise_methodql.html (added) +++ websites/production/openjpa/content/builds/2.4.0/apache-openjpa/docs/ref_guide_enterprise_methodql.html Mon Jun 1 20:19:00 2015 @@ -0,0 +1,80 @@ + + + 5.  MethodQL

5.  + MethodQL +

+ + + +

+If JPQL and SQL queries do not match your needs, OpenJPA also allows you to name +a Java method to use to load a set of objects. In a MethodQL + query, the query string names a static method to invoke to determine +the matching objects: +

+
+import org.apache.openjpa.persistence.*;
+
+...
+
+// the method query language is 'openjpa.MethodQL'.
+// set the query string to the target method to execute, prefixed by fullly-
+// qualified class name.
+// If a candidate class has been specified for the query, then if the class is 
+// in the candidate class' package or in the query imports, you can omit the 
+// package. If the method is in the candidate class, you can omit the class name 
+// and just specify the method name.
+
+  OpenJPAEntityManager oem = OpenJPAPersistence.cast(emf);
+  OpenJPAQuery q = oem.createQuery("openjpa.MethodQL", "com.xyz.Finder.getByName");
+
+// parameters are passed the same way as in standard queries
+// but you have to declare the parameters with their types on the implementation
+
+// Unwrap the implementation and declare parameters with types in a 
+// comma-separated list
+  q.unwrap(org.apache.openjpa.kernel.Query.class)
+   .declareParameters("String firstName, String lastName");
+
+  q.setParameter("firstName", "Fred").setParameter("lastName", "Lucas");
+
+// this executes the target method to get the results
+  List results = q.getResultList();
+
+// The result is returned as a list but the element(s) in the list is determined 
+// by the returned value of the target method
+ 
+
+

+For datastore queries, the method must have the following signature: +

+
+public static ResultObjectProvider xxx(StoreContext ctx, ClassMetaData meta, boolean subclasses, Map params, FetchConfiguration  fetch)
+
+

+The returned result object provider should produce objects of the candidate +class that match the method's search criteria. If the returned objects do not +have all fields in the given fetch configuration loaded, OpenJPA will make +additional trips to the datastore as necessary to fill in the data for the +missing fields. +

+

+In-memory execution is slightly different, taking in one object at a time and +returning a boolean on whether the object matches the query: +

+
+public static boolean xxx(StoreContext ctx, ClassMetaData meta, boolean subclasses, Object obj, Map params, FetchConfiguration fetch)
+
+

+In both method versions, the given params map contains the +names and values of all the parameters for the query. +

+
\ No newline at end of file Propchange: websites/production/openjpa/content/builds/2.4.0/apache-openjpa/docs/ref_guide_enterprise_methodql.html ------------------------------------------------------------------------------ svn:eol-style = native Added: websites/production/openjpa/content/builds/2.4.0/apache-openjpa/docs/ref_guide_enterprise_trans.html ============================================================================== --- websites/production/openjpa/content/builds/2.4.0/apache-openjpa/docs/ref_guide_enterprise_trans.html (added) +++ websites/production/openjpa/content/builds/2.4.0/apache-openjpa/docs/ref_guide_enterprise_trans.html Mon Jun 1 20:19:00 2015 @@ -0,0 +1,110 @@ + + + 2.  Integrating with the Transaction Manager

2.  + Integrating with the Transaction Manager +

+ + + + + +

+OpenJPA EntityManagers have the ability to automatically +synchronize their transactions with an external transaction manager. Whether +or not EntityManagers from a given +EntityManagerFactory exhibit this behavior by default depends on +the transaction type you set for the factory's persistence unit in +your persistence.xml file. OpenJPA uses the given +transaction type internally to set the +openjpa.TransactionMode + configuration property. This property accepts the following +modes: +

+
+

+You can override the global transaction mode setting when you obtain an +EntityManager using the + +EntityManagerFactory's +createEntityManager(Map props) method. Simply set the +openjpa.TransactionMode key of the given Map + to the desired value. +

+

Note

+

+You can also override the openjpa.ConnectionUserName, +openjpa.ConnectionPassword, and +openjpa.ConnectionRetainMode settings using the given +Map. +

+
+

+ +In order to use global transactions, OpenJPA must be able to access the +application server's +javax.transaction.TransactionManager. OpenJPA can automatically +discover the transaction manager for most major application servers. +Occasionally, however, you might have to point OpenJPA to the transaction +manager for an unrecognized or non-standard application server setup. This is +accomplished through the +openjpa.ManagedRuntime configuration property. This +property describes an + +org.apache.openjpa.ee.ManagedRuntime implementation to use +for transaction manager discovery. You can specify your own implementation, +or use one of the built-ins: +

+
+

+See the Javadoc for of each class for details on the bean properties +you can pass to these plugins in your configuration string. +

+

Example 8.1. Configuring Transaction Manager Integration

+ +
+<property name="openjpa.TransactionMode" value="managed"/>
+<property name="openjpa.ManagedRuntime" value="jndi(TransactionManagerName=java:/TransactionManager)"/>
+
+

+
\ No newline at end of file Propchange: websites/production/openjpa/content/builds/2.4.0/apache-openjpa/docs/ref_guide_enterprise_trans.html ------------------------------------------------------------------------------ svn:eol-style = native Added: websites/production/openjpa/content/builds/2.4.0/apache-openjpa/docs/ref_guide_enterprise_xa.html ============================================================================== --- websites/production/openjpa/content/builds/2.4.0/apache-openjpa/docs/ref_guide_enterprise_xa.html (added) +++ websites/production/openjpa/content/builds/2.4.0/apache-openjpa/docs/ref_guide_enterprise_xa.html Mon Jun 1 20:19:00 2015 @@ -0,0 +1,92 @@ + + + 3.  XA Transactions

3.  + XA Transactions +

3.1. + Using OpenJPA with XA Transactions +
+ + + +

+The X/Open Distributed Transaction Processing (X/Open DTP) model, designed by +The Open Group (a vendor consortium), +defines a standard communication architecture that provides the following: +

+
+

+The X/Open DTP XA standard defines the application programming interfaces that a +resource manager uses to communicate with a transaction manager. The XA +interfaces enable resource managers to join transactions, to perform two-phase +commit, and to recover in-doubt transactions following a failure. +

+

3.1.  + Using OpenJPA with XA Transactions +

+ +

+OpenJPA supports XA-compliant transactions when used in a properly configured +managed environment. The following components are required: +

+
  • +

    +A managed environment that provides an XA compliant transaction manager. +Examples of this are application servers such as WebLogic or JBoss. +

    +
  • +

    +Instances of a javax.sql.XADataSource for each of the +DataSources that OpenJPA will use. +

    +
+

+Given these components, setting up OpenJPA to participate in distributed +transactions is a simple two-step process: +

+
  1. +

    +Integrate OpenJPA with your application server's transaction manager, as +detailed in Section 2, “ + Integrating with the Transaction Manager + ” above. +

    +
  2. +

    +Point OpenJPA at an enlisted XADataSource, and configure +a second non-enlisted data source. See +Section 2.1, “ + Managed and XA DataSources + ”. +

    +
+
+
\ No newline at end of file Propchange: websites/production/openjpa/content/builds/2.4.0/apache-openjpa/docs/ref_guide_enterprise_xa.html ------------------------------------------------------------------------------ svn:eol-style = native Added: websites/production/openjpa/content/builds/2.4.0/apache-openjpa/docs/ref_guide_event.html ============================================================================== --- websites/production/openjpa/content/builds/2.4.0/apache-openjpa/docs/ref_guide_event.html (added) +++ websites/production/openjpa/content/builds/2.4.0/apache-openjpa/docs/ref_guide_event.html Mon Jun 1 20:19:00 2015 @@ -0,0 +1,256 @@ + + + 2.  Remote Event Notification Framework

2.  + Remote Event Notification Framework +

2.1. + Remote Commit Provider Configuration +
2.1.1. + JMS +
2.1.2. + TCP +
2.1.3. + Common Properties +
2.2. + Customization +
+ + + +

+ + +The remote event notification framework allows a subset of the information +available through OpenJPA's transaction events (see +Section 7, “ + Transaction Events + ”) to be broadcast to remote +listeners. OpenJPA's data cache, for +example, uses remote events to remain synchronized when deployed in multiple +JVMs. +

+

+To enable remote events, you must configure the EntityManagerFactory + to use a RemoteCommitProvider (see below). +

+

+When a RemoteCommitProvider is properly configured, you can +register + +RemoteCommitListeners that will be alerted with +a list of modified object ids whenever a transaction on a remote machine +successfully commits. +

+

2.1.  + Remote Commit Provider Configuration +

+ + +

+OpenJPA includes built in remote commit providers for JMS and TCP communication. +

+

2.1.1.  + JMS +

+ + +

+The JMS remote commit provider can be configured by setting the + +openjpa.RemoteCommitProvider property to contain the +appropriate configuration properties. The JMS provider understands the following +properties: +

+
  • +

    +Topic: The topic that the remote commit provider should +publish notifications to and subscribe to for notifications sent from other +JVMs. Defaults to topic/OpenJPACommitProviderTopic +

    +
  • +

    +TopicConnectionFactory: The JNDI name of a +javax.jms.TopicConnectionFactory factory to use for finding topics. +Defaults to java:/ConnectionFactory. This setting may vary +depending on the application server in use; consult the application server's +documentation for details of the default JNDI name for the +javax.jms.TopicConnectionFactory instance. For example, under +Weblogic, the JNDI name for the TopicConnectionFactory is +javax.jms.TopicConnectionFactory. +

    +
  • +

    +ExceptionReconnectAttempts: The number of times to attempt +to reconnect if the JMS system notifies OpenJPA of a serious connection error. +Defaults to 0, meaning OpenJPA will log the error but otherwise ignore it, +hoping the connection is still valid. +

    +
  • +

    +*: All other configuration properties will be interpreted as +settings to pass to the JNDI InitialContext on +construction. For example, you might set the java.naming.provider.url + property to the URL of the context provider. +

    +
+

+To configure a factory to use the JMS provider, your properties might look like +the following: +

+

Example 12.2.  + JMS Remote Commit Provider Configuration +

+ +
+<property name="openjpa.RemoteCommitProvider"
+    value="jms(ExceptionReconnectAttempts=5)"/>
+
+

+

Note

+

+Because of the nature of JMS, it is important that you invoke +EntityManagerFactory.close when finished with a factory. If you do +not do so, a daemon thread will stay up in the JVM, preventing the JVM from +exiting. +

+
+
+

2.1.2.  + TCP +

+ + +

+The TCP remote commit provider has several options that are defined as host +specifications containing a host name or IP address and an optional port +separated by a colon. For example, the host specification +saturn.bea.com:1234 represents an InetAddress +retrieved by invoking InetAddress.getByName("saturn.bea.com") + and a port of 1234. +

+

+ +The TCP provider can be configured by setting the +openjpa.RemoteCommitProvider plugin property to contain the +appropriate configuration settings. The TCP provider understands the following +properties: +

+
  • +

    +Port: The TCP port that the provider should listen on for +commit notifications. Defaults to 5636. +

    +
  • +

    +Addresses: A semicolon-separated list of IP addresses to +which notifications should be sent. No default value. +

    +
  • +

    +NumBroadcastThreads: The number of threads to create for the +purpose of transmitting events to peers. You should increase this value as the +number of concurrent transactions increases. The maximum number of concurrent +transactions is a function of the size of the connection pool. See the +MaxActive property of +openjpa.ConnectionFactoryProperties in +Section 1, “ + Using the OpenJPA DataSource + ”. Setting a value of 0 will +result in behavior where the thread invoking commit +will perform the broadcast directly. Defaults to 2. +

    +
  • +

    +RecoveryTimeMillis: Amount of time to wait in milliseconds +before attempting to reconnect to a peer of the cluster when connectivity to the +peer is lost. Defaults to 15000. +

    +
  • +

    +MaxIdle: The number of TCP sockets (channels) to keep open +to each peer in the cluster for the transmission of events. Defaults to 2. +

    +
  • +

    +MaxActive: The maximum allowed number of TCP sockets +(channels) to open simultaneously between each peer in the cluster. Defaults to +2. +

    +
+

+To configure a factory to use the TCP provider, your properties might look like +the following: +

+

Example 12.3.  + TCP Remote Commit Provider Configuration +

+ +
+<property name="openjpa.RemoteCommitProvider"
+    value="tcp(Addresses=10.0.1.10;10.0.1.11;10.0.1.12;10.0.1.13)"/>
+
+

+
+

2.1.3.  + Common Properties +

+ + +

+In addition to the provider-specific configuration options above, all providers +accept the following plugin properties: +

+
  • +

    +TransmitPersistedObjectIds: Whether remote commit events +will include the object ids of instances persisted in the transaction. By +default only the class names of types persisted in the transaction are sent. +This results in smaller events and more efficient network utilization. If you +have registered your own remote commit listeners, however, you may require the +persisted object ids as well. +

    +
+

+To transmit persisted object ids in our remote commit events using the JMS +provider, we modify the previous example as follows: +

+

Example 12.4.  + JMS Remote Commit Provider transmitting Persisted Object Ids +

+ +
+<property name="openjpa.RemoteCommitProvider"
+    value="jms(ExceptionReconnectAttempts=5, TransmitPersistedObjectIds=true)"/>
+
+

+
+
+

2.2.  + Customization +

+ + +

+You can develop additional mechanisms for remote event notification be by +creating an implementation of the + + RemoteCommitProvider interface, possibly by +extending the + +AbstractRemoteCommitProvider abstract class.. +

+
+
\ No newline at end of file Propchange: websites/production/openjpa/content/builds/2.4.0/apache-openjpa/docs/ref_guide_event.html ------------------------------------------------------------------------------ svn:eol-style = native Added: websites/production/openjpa/content/builds/2.4.0/apache-openjpa/docs/ref_guide_fetch.html ============================================================================== --- websites/production/openjpa/content/builds/2.4.0/apache-openjpa/docs/ref_guide_fetch.html (added) +++ websites/production/openjpa/content/builds/2.4.0/apache-openjpa/docs/ref_guide_fetch.html Mon Jun 1 20:19:00 2015 @@ -0,0 +1,360 @@ + + + 7.  Fetch Groups

7.  + Fetch Groups +

7.1. + Custom Fetch Groups +
7.2. + Custom Fetch Group Configuration +
7.3. + Per-field Fetch Configuration +
7.4. + Implementation Notes +
+ + +

+Fetch groups are sets of fields that load together. They can be used to pool +together associated fields in order to provide performance improvements over +standard data fetching. Specifying fetch groups allows for tuning of lazy +loading and eager fetching behavior. +

+

+The JPA Overview's Section 2.7.1, “ + Fetch Type + ” describes how +to use JPA metadata annotations to control whether a field is fetched eagerly or +lazily. Fetch groups add a dynamic aspect to this standard ability. As you will +see, OpenJPA's JPA extensions allow you can add and remove fetch groups at +runtime to vary the sets of fields that are eagerly loaded. +

+

7.1.  + Custom Fetch Groups +

+ +

+OpenJPA places any field that is eagerly loaded according to the JPA metadata +rules into the built-in default fetch group. As its name +implies, the default fetch group is active by default. You may also +define your own named fetch groups and activate or deactivate them at runtime, +as described later in this chapter. OpenJPA will eagerly-load the fields in all +active fetch groups when loading objects from the datastore. +

+

+You create fetch groups with the + +org.apache.openjpa.persistence.FetchGroup +annotation. If your class only has one custom fetch group, you can place this +annotation directly on the class declaration. Otherwise, use the + +org.apache.openjpa.persistence.FetchGroups +annotation to declare an array of individual FetchGroup +values. The FetchGroup annotation has the following +properties: +

+
  • +

    +String name: The name of the fetch group. Fetch group names +are global, and are expected to be shared among classes. For example, a shopping +website may use a detail fetch group in each product class +to efficiently load all the data needed to display a product's "detail" page. +The website might also define a sparse list fetch group +containing only the fields needed to display a table of products, as in a search +result. +

    +

    +The following names are reserved for use by OpenJPA: default +, values, all, none, +and any name beginning with jdo, jpa, or +openjpa. +

    +
  • +

    +FetchAttribute[] attributes: The set of persistent fields or +properties in the fetch group. +

    +
  • +

    +String[] fetchGroups: Other fetch groups whose fields to +include in this group. +

    +
+

+As you might expect, listing a + +org.apache.openjpa.persistence.FetchAttribute +within a FetchGroup includes the corresponding persistent +field or property in the fetch group. Each FetchAttribute +has the following properties: +

+
  • +

    +String name: The name of the persistent field or property to +include in the fetch group. +

    +
  • +

    +recursionDepth: If the attribute represents a relation, the +maximum number of same-typed relations to eager-fetch from this field. Defaults +to 1. For example, consider an Employee class with a +manager field, also of type Employee. +When we load an Employee and the +manager field is in an active fetch group, the recursion depth (along +with the max fetch depth setting, described below) determines whether we only +retrieve the target Employee and his manager (depth 1), +or whether we also retrieve the manager's manager (depth 2), or the manager's +manager's manager (depth 3), etc. Use -1 for unlimited depth. +

    +
+

Example 5.19.  + Custom Fetch Group Metadata +

+ +

+Creates a detail fetch group consisting of the +publisher and articles relations. +

+
+import org.apache.openjpa.persistence.*;
+
+@Entity
+@FetchGroups({
+    @FetchGroup(name="detail", attributes={
+        @FetchAttribute(name="publisher"),
+        @FetchAttribute(name="articles")
+    }),
+    ...
+})
+public class Magazine {
+   ...
+}
+
+

+

+A field can be a member of any number of fetch groups. A field can also +declare a load fetch group. +When you access a lazy-loaded field for the first time, OpenJPA makes a +datastore trip to fetch that field's data. Sometimes, however, you know +that whenever you access a lazy field A, you're likely to access lazy fields B +and C as well. Therefore, it would be more efficient to fetch the data for A, +B, and C in the same datastore trip. By setting A's load fetch group to the +name of a fetch group containing B and +C, you can tell OpenJPA to load all of these fields together when A is first +accessed. +

+

+Use OpenJPA's + +org.apache.openjpa.persistence.LoadFetchGroup +annotation to specify the load fetch group of any persistent field. The value of +the annotation is the name of a declared fetch group whose members should be +loaded along with the annotated field. +

+

Example 5.20.  + Load Fetch Group Metadata +

+ +
+import org.apache.openjpa.persistence.*;
+
+@Entity
+@FetchGroups({
+    @FetchGroup(name="detail", attributes={
+        @FetchAttribute(name="publisher"),
+        @FetchAttribute(name="articles")
+    }),
+    ...
+})
+public class Magazine {
+
+   @ManyToOne(fetch=FetchType.LAZY)
+   @LoadFetchGroup("detail")
+   private Publisher publisher;
+
+   ...
+}
+
+

+
+

7.2.  + Custom Fetch Group Configuration +

+ + +

+ +You can control the default set of fetch groups with the +openjpa.FetchGroups + configuration property. Set this property to a comma-separated list of +fetch group names. +

+

+You can also set the system's default maximum fetch depth with the +openjpa.MaxFetchDepth + configuration property. The maximum fetch depth determines how "deep" +into the object graph to traverse when loading an instance. For example, with +a MaxFetchDepth of 1, OpenJPA will load at most the target +instance and its immediate relations. With a MaxFetchDepth +of 2, OpenJPA may load the target instance, its immediate relations, and +the relations of those relations. This works to arbitrary depth. In fact, +the default MaxFetchDepth value is -1, which symbolizes +infinite depth. Under this setting, OpenJPA will fetch configured relations +until it reaches the edges of the object graph. Of course, which relation +fields are loaded depends on whether the fields are eager or lazy, and on the +active fetch groups. A fetch group member's recursion depth may also limit +the fetch depth to something less than the configured maximum. +

+

+OpenJPA's OpenJPAEntityManager and +OpenJPAQuery extensions to the standard EntityManager + and Query interfaces provide access to a + +org.apache.openjpa.persistence.FetchPlan object. +The FetchPlan maintains the set of active fetch groups +and the maximum fetch depth. It begins with the groups and depth defined in the +openjpa.FetchGroups and openjpa.MaxFetchDepth + properties, but allows you to add or remove groups and change the +maximum fetch depth for an individual EntityManager or +Query through the methods below. +

+
+public FetchPlan addFetchGroup(String group);
+public FetchPlan addFetchGroups(String... groups);
+public FetchPlan addFetchGroups(Collection groups);
+public FetchPlan removeFetchGrop(String group);
+public FetchPlan removeFetchGroups(String... groups);
+public FetchPlan removeFetchGroups(Collection groups);
+public FetchPlan resetFetchGroups();
+public Collection<String> getFetchGroups();
+public void clearFetchGroups();
+public FetchPlan setMaxFetchDepth(int depth);
+public int getMaxFetchDepth();
+
+

+Chapter 9, + Runtime Extensions + details the +OpenJPAEntityManager, OpenJPAQuery, and +FetchPlan interfaces. +

+

Example 5.21.  + Using the FetchPlan +

+ +
+import org.apache.openjpa.persistence.*;
+
+...
+
+OpenJPAQuery kq = OpenJPAPersistence.cast(em.createQuery(...));
+kq.getFetchPlan().setMaxFetchDepth(3).addFetchGroup("detail");
+List results = kq.getResultList();
+
+

+
+

7.3.  + Per-field Fetch Configuration +

+ + +

+In addition to controlling fetch configuration on a per-fetch-group basis, you +can configure OpenJPA to include particular fields in the current fetch +plan. This allows you to add individual fields that are not in the +default fetch group or in any other active fetch groups to the set of +fields that will be eagerly loaded from the database. +

+

+OpenJPA FetchPlan methods: +

+
+public FetchPlan addField(String field);
+public FetchPlan addFields(String... fields);
+public FetchPlan addFields(Class cls, String... fields);
+public FetchPlan addFields(Collection fields);
+public FetchPlan addFields(Class cls, Collection fields);
+public FetchPlan removeField(String field);
+public FetchPlan removeFields(String... fields);
+public FetchPlan removeFields(Class cls, String... fields);
+public FetchPlan removeFields(Collection fields);
+public FetchPlan removeFields(Class cls, Collection fields);
+public Collection<String> getFields();
+public void clearFields();
+
+

+The methods that take only string arguments use the fully-qualified field name, +such as org.mag.Magazine.publisher. Similarly, +getFields returns the set of fully-qualified field names. In all +methods, the named field must be defined in the class specified in the +invocation, not a superclass. So, if the field publisher is +defined in base class Publication rather than subclass +Magazine, you must invoke addField +(Publication.class, "publisher") and not addField +(Magazine.class, "publisher"). This is stricter than Java's default +field-masking algorithms, which would allow the latter method behavior if +Magazine did not also define a field called +publisher. +

+ +

+To include the fields defined in a super class by the subclass or to distinguish +between fields that are defined in both super- and subclass, +set setExtendedPathLookup(boolean) on FetchPlan + to true. By default, this option is set to +false, to reduce more extensive lookups for predominant use +cases. +

+ +

+In order to avoid the cost of reflection, OpenJPA does not perform any +validation of the field name / class name pairs that you put into the fetch +configuration. If you specify non-existent class / field pairs, nothing adverse +will happen, but you will receive no notification of the fact that the specified +configuration is not being used. +

+

Example 5.22.  + Adding an Eager Field +

+ +
+import org.apache.openjpa.persistence.*;
+
+...
+
+OpenJPAEntityManager kem = OpenJPAPersistence.cast(em);
+kem.getFetchPlan().addField(Magazine.class, "publisher");
+Magazine mag = em.find(Magazine.class, magId);
+
+

+
+

7.4.  + Implementation Notes +

+ +
  • +

    +Even when a direct relation is not eagerly fetched, OpenJPA selects the foreign +key columns and caches the values. This way when you do traverse the relation, +OpenJPA can often find the related object in its cache, or at least avoid joins +when loading the related object from the database. +

    +
  • +

    +The above implicit foreign key-selecting behavior does not always apply when the +relation is in a subclass table. If the subclass table would not otherwise be +joined into the select, OpenJPA avoids the extra join just to select the foreign +key values. +

    +
+ + +
+
\ No newline at end of file Propchange: websites/production/openjpa/content/builds/2.4.0/apache-openjpa/docs/ref_guide_fetch.html ------------------------------------------------------------------------------ svn:eol-style = native Added: websites/production/openjpa/content/builds/2.4.0/apache-openjpa/docs/ref_guide_instrumentation.html ============================================================================== --- websites/production/openjpa/content/builds/2.4.0/apache-openjpa/docs/ref_guide_instrumentation.html (added) +++ websites/production/openjpa/content/builds/2.4.0/apache-openjpa/docs/ref_guide_instrumentation.html Mon Jun 1 20:19:00 2015 @@ -0,0 +1,88 @@ + + + Chapter 16.  Instrumentation

Chapter 16.  + Instrumentation +

Table of Contents

1. + Configuration +
1.1. + JMX Platform MBean Enablement +
2. + Custom Providers and Instruments +
+ + +

+ OpenJPA provides the ability to instrument various aspects of runtime + operation. Instrumentation involves an instrumentation provider for base instrumentation + capabilities and instruments for instrumenting various aspects of OpenJPA. OpenJPA + includes a default instrumentation provider for JMX Platform MBeans. MBean-based instruments + are provided for the data cache, query cache, and query SQL cache. When enabled, + JMX-based remote monitoring tools such as + + JConsole can be used to monitor various + metrics tracked by OpenJPA's caches by accessing MBeans registered under domain + org.apache.openjpa. Additionally, custom applications can gather metrics by using the + JMX API to query OpenJPA's MBeans. The openjpa-integration-jmx + integration module contains an example of how to access the cache MBeans within program code. +

+

1.  + Configuration +

+ + +

+ Instrumentation is enabled using the openjpa.Instrumentation + configuration property. The base value is the instrumentation provider. The + alias "jmx" enables the JMX Platform MBean provider. Instruments are specified + on the Instrument attribute of the provider. Multiple instruments can be specified + by enclosing the value in single quotes and specifying each instrument or instrument + alias as a comma separated list. For example: +

+
+            <!--  Enable caches and cache statistics -->
+            <property name="openjpa.DataCache" value="true(EnableStatistics=true)"/>
+            <property name="openjpa.QueryCache" value="true(EnableStatistics=true)"/>
+            <property name="openjpa.jdbc.QuerySQLCache" value="true(EnableStatistics=true)"/>
+
+            <!--  Enable jmx provider and instruments for Data, Query, and QuerySQL caches -->
+            <property name="openjpa.Instrumentation" value="jmx(Instrument='DataCache,QueryCache,QuerySQLCache')"/>
+        
+

1.1.  + JMX Platform MBean Enablement +

+ + +

+ The built-in JMX Platform MBean provider can be used to monitor OpenJPA + runtime information out-of-band. This provider is based upon the Platform MBean support included + in the JDK. The JDK provides options for enabling secure connectivity and authentication. + These options require additional configuration options and may require encryption + keys to be installed on the local and remote systems. To enable simple, non-secure, non-authenticated + monitoring of your application, specify the -Dcom.sun.management.jmxremote.authenticate=false and + -Dcom.sun.management.jmxremote.ssl=false directives on the java command line invocation. To enable + remote instrumentation on a specific port, specify which port to use on the directive + -Dcom.sun.management.jmxremote.port=<port>. + For example: +

+            java -cp openjpa-all-2.2.0.jar:myApplication.jar -Dcom.sun.management.jmxremote.authenticate=false
+            -Dcom.sun.management.jmxremote.ssl=false -Dcom.sun.management.jmxremote.port=8888 com.my.app.Main
+            

+

+

+ Additional information regarding the use and configuration of JMX Platform MBeans + can be found in the + + Java Management Extensions (JMX) Technology Overview. +

+
+
+ +
\ No newline at end of file Propchange: websites/production/openjpa/content/builds/2.4.0/apache-openjpa/docs/ref_guide_instrumentation.html ------------------------------------------------------------------------------ svn:eol-style = native Added: websites/production/openjpa/content/builds/2.4.0/apache-openjpa/docs/ref_guide_instrumentation_custom.html ============================================================================== --- websites/production/openjpa/content/builds/2.4.0/apache-openjpa/docs/ref_guide_instrumentation_custom.html (added) +++ websites/production/openjpa/content/builds/2.4.0/apache-openjpa/docs/ref_guide_instrumentation_custom.html Mon Jun 1 20:19:00 2015 @@ -0,0 +1,53 @@ + + + 2.  Custom Providers and Instruments

2.  + Custom Providers and Instruments +

+ + +

+ OpenJPA includes built-in support for a JMX Platform MBean provider, but a custom instrumentation + providers can be created by implementing the + + InstrumentationProvider interface or more simply by extending + + AbstractInstrumentationProvider. To use the custom instrumentation provider, + include the class in your classpath and specify the class name as the base value on the + openjpa.Instrumentation configuration property. +

+

+ OpenJPA includes instruments for various caches, but you can also create your own instruments. To + create a custom instrument you need to implement the + + Instrument interface or more simply extend + + AbstractInstrument. If you are building a Platform MBean JMX-based + instrument this effort can be simplified by extending + + JMXInstrument. If you create your own custom + provider, class name aliases can be registered within the provider to simplify configuration. For example, + the instrument com.my.app.MySQLInstrument could be aliased as + MySQLInstrument within custom provider + com.my.app.InstrumentationProvider. +

+

+ OpenJPA provides the ability to plug in custom instruments and gives instruments direct access to the + configuration, but it is up to the creator of the instrument to add the internal monitoring. This often + requires modifying or extending base OpenJPA classes (such as the Broker) or using a byte-code weaving + tool such as AspectJ to produce aspect-based instruments. +

+

+ Here is an example of how a custom instrumentation provider could be enabled with an instrument class + aliased by the provider as MySQLInstrument. +

+
+            <!--  Enable custom provider and instrument -->
+            <property name="openjpa.Instrumentation" value="com.my.app.InstrumentationProvider(Instrument='MySQLInstrument')"/>
+        
+
\ No newline at end of file Propchange: websites/production/openjpa/content/builds/2.4.0/apache-openjpa/docs/ref_guide_instrumentation_custom.html ------------------------------------------------------------------------------ svn:eol-style = native