Author: sergiykarpenko Date: 2010-08-05 09:44:26 -0400 (Thu, 05 Aug 2010) New Revision: 2886 Modified: jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/concepts/jcr-usage.xml jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/statistics.xml Log: EXOJCR-869: few fixes Modified: jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/concepts/jcr-usage.xml =================================================================== --- jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/concepts/jcr-usage.xml 2010-08-05 12:40:40 UTC (rev 2885) +++ jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/concepts/jcr-usage.xml 2010-08-05 13:44:26 UTC (rev 2886) @@ -12,50 +12,72 @@ <section> <title>Obtaining a Repository object</title> - <para>A javax.jcr.Repository object can be obtained either by ...: * - Using the eXo Container "native" mechanism. All Repositories are kept - with a single RepositoryService component. So it can be obtained from - eXo Container, described as following:</para> + <para>A javax.jcr.Repository object can be obtained either by ...: + <itemizedlist> + <listitem> + <para>Using the eXo Container "native" mechanism. All Repositories + are kept with a single RepositoryService component. So it can be + obtained from eXo Container, described as + following:<programlisting> RepositoryService repositoryService = (RepositoryService) container.getComponentInstanceOfType(RepositoryService.class); + Repository repository = repositoryService.getRepository("repositoryName"); </programlisting></para> + </listitem> - <programlisting> RepositoryService repositoryService = (RepositoryService) container.getComponentInstanceOfType(RepositoryService.class); - Repository repository = repositoryService.getRepository("repositoryName"); </programlisting> - - <para>* Using the eXo Container "native" mechanism with a thread local - saved "current" repository (especially if you plan using a single - repository which covers more than 90% of use cases)</para> - - <programlisting> // set current repository at initial time + <listitem> + <para>Using the eXo Container "native" mechanism with a thread + local saved "current" repository (especially if you plan using a + single repository which covers more than 90% of use + cases)<programlisting> // set current repository at initial time RepositoryService repositoryService = (RepositoryService) container.getComponentInstanceOfType(RepositoryService.class); repositoryService.setCurrentRepositoryName("repositoryName"); .... // retrieve and use this repository - Repository repository = repositoryService.getCurrentRepository();</programlisting> + Repository repository = repositoryService.getCurrentRepository();</programlisting></para> + </listitem> - <para>* Using JNDI as specified in JSR-170. This way you have to - configure the reference (see eXo <link linkend="Kernel.JNDINaming"> JNDI - Naming configuration </link> )</para> - - <programlisting> Context ctx = new InitialContext(); - Repository repository =(Repository) ctx.lookup("repositoryName");</programlisting> + <listitem> + <para>Using JNDI as specified in JSR-170. This way you have to + configure the reference (see eXo <link + linkend="Kernel.JNDINaming">JNDI Naming configuration</link> + )<programlisting> Context ctx = new InitialContext(); + Repository repository =(Repository) ctx.lookup("repositoryName");</programlisting></para> + </listitem> + </itemizedlist></para> </section> <section> <title>JCR Session common considerations</title> - <para>* Remember javax.jcr.Session is not a thread safe object. - <emphasis role="bold">Never try to share it between threads</emphasis> * - Do not use <emphasis role="bold">System session</emphasis> from the - <emphasis role="bold">user</emphasis> related code because a system - session has <emphasis role="bold">unlimited rights</emphasis>. Call - ManageableRepository.getSystemSession() from <emphasis - role="bold">process</emphasis> related code only. * Call - Session.logout() explicitly to <emphasis role="bold">release - resources</emphasis> assigned to the session. * When designing your - application take care of the Session policy inside your application. Two - <emphasis role="bold">strategies</emphasis> are possible: <emphasis - role="bold">Stateless</emphasis> (Session per business request) and - <emphasis role="bold">Stateful</emphasis> (Session per User) or some - mix.</para> + <para><itemizedlist> + <listitem> + <para>Remember javax.jcr.Session is not a thread safe object. + <emphasis role="bold">Never try to share it between + threads</emphasis>.</para> + </listitem> + + <listitem> + <para>Do not use <emphasis role="bold">System session</emphasis> + from the <emphasis role="bold">user</emphasis> related code + because a system session has <emphasis role="bold">unlimited + rights</emphasis>. Call ManageableRepository.getSystemSession() + from <emphasis role="bold">process</emphasis> related code + only.</para> + </listitem> + + <listitem> + <para>Call Session.logout() explicitly to <emphasis + role="bold">release resources</emphasis> assigned to the + session.</para> + </listitem> + + <listitem> + <para>When designing your application take care of the Session + policy inside your application. Two <emphasis + role="bold">strategies</emphasis> are possible: <emphasis + role="bold">Stateless</emphasis> (Session per business request) + and <emphasis role="bold">Stateful</emphasis> (Session per User) + or some mix.</para> + </listitem> + </itemizedlist></para> </section> </section> @@ -154,7 +176,7 @@ provides two implementations :</para> <table> - <title></title> + <title>SessionProvider implementations</title> <tgroup cols="3"> <thead> @@ -192,14 +214,25 @@ <para>For any implementation, your code should follow the following sequence :</para> - <para>* Call SessionProviderService.setSessionProvider(Object key, - SessionProvider sessionProvider) at the beginning of a business request - for Stateless application or application's session for Statefull policy. - * Call SessionProviderService.getSessionProvider(Object key) for - obtaining a SessionProvider object * Call - SessionProviderService.removeSessionProvider(Object key) at the end of a - business request for Stateless application or application's session for - Statefull policy.</para> + <itemizedlist> + <listitem> + <para>Call SessionProviderService.setSessionProvider(Object key, + SessionProvider sessionProvider) at the beginning of a business + request for Stateless application or application's session for + Statefull policy.</para> + </listitem> + + <listitem> + <para>Call SessionProviderService.getSessionProvider(Object key) for + obtaining a SessionProvider object</para> + </listitem> + + <listitem> + <para>Call SessionProviderService.removeSessionProvider(Object key) + at the end of a business request for Stateless application or + application's session for Statefull policy.</para> + </listitem> + </itemizedlist> </section> </section> </chapter> Modified: jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/statistics.xml =================================================================== --- jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/statistics.xml 2010-08-05 12:40:40 UTC (rev 2885) +++ jcr/branches/1.12.x/docs/reference/en/src/main/docbook/en-US/modules/jcr/statistics.xml 2010-08-05 13:44:26 UTC (rev 2886) @@ -1,465 +1,465 @@ -<?xml version="1.0" encoding="UTF-8"?> -<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" -"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> -<chapter id="JCR.Statistics"> - <?dbhtml filename="ch-statistics"?> - - <title>eXo JCR statistics</title> - - <section> - <title>Statistics on the Database Access Layer</title> - - <para>In order to have a better idea of the time spent into the database - access layer, it cans be interesting to get some statistics on that part - of the code, knowing that most of the time spent into eXo JCR is mainly - the database access. This statistics will then allow you to identify - without using any profiler what is anormally slow in this layer, which - could help to fix the problem quickly.</para> - - <para>In case you use - <envar>org.exoplatform.services.jcr.impl.storage.jdbc.optimisation.CQJDBCWorkspaceDataContainer</envar> - or - <envar>org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer</envar> - as <envar>WorkspaceDataContainer</envar>, you can get statistics on the - time spent into the database access layer. The database access layer (in - eXo JCR) is represented by the methods of the interface - <envar>org.exoplatform.services.jcr.storage.WorkspaceStorageConnection</envar>, - so for all the methods defined in this interface, we can have the - following figures:</para> - - <itemizedlist> - <listitem> - <para>The minimum time spent into the method.</para> - </listitem> - - <listitem> - <para>The maximum time spent into the method.</para> - </listitem> - - <listitem> - <para>The average time spent into the method.</para> - </listitem> - - <listitem> - <para>The total amount of time spent into the method.</para> - </listitem> - - <listitem> - <para>The total amount of times the method has been called.</para> - </listitem> - </itemizedlist> - - <para>Those figures are also available globaly for all the methods which - gives us the global behavior of this layer.</para> - - <para>If you want to enable the statistics, you just need to set the JVM - parameter called - <emphasis>JDBCWorkspaceDataContainer.statistics.enabled</emphasis> to - <emphasis>true</emphasis>. The corresponding CSV file is - <emphasis>StatisticsJDBCStorageConnection-${creation-timestamp}.csv</emphasis> - for more details about how the csv files are managed please refer to the - section dedicated to the statistics manager.</para> - - <para>The format of each column header is ${method-alias}-${metric-alias}. - The metric alias are described in the statistics manager section.</para> - - <table> - <title>Method Alias</title> - - <tgroup cols="2"> - <tbody> - <row> - <entry>global</entry> - - <entry>This is the alias for all the methods.</entry> - </row> - - <row> - <entry>getItemDataById</entry> - - <entry>This is the alias for the method - <emphasis>getItemData(String identifier).</emphasis></entry> - </row> - - <row> - <entry>getItemDataByNodeDataNQPathEntry</entry> - - <entry>This is the alias for the method - <emphasis>getItemData(NodeData parentData, QPathEntry - name).</emphasis></entry> - </row> - - <row> - <entry>getChildNodesData</entry> - - <entry>This is the alias for the method - <emphasis>getChildNodesData(NodeData parent).</emphasis></entry> - </row> - - <row> - <entry>getChildNodesCount</entry> - - <entry>This is the alias for the method - <emphasis>getChildNodesCount(NodeData parent).</emphasis></entry> - </row> - - <row> - <entry>getChildPropertiesData</entry> - - <entry>This is the alias for the method - <emphasis>getChildPropertiesData(NodeData - parent).</emphasis></entry> - </row> - - <row> - <entry>listChildPropertiesData</entry> - - <entry>This is the alias for the method - <emphasis>listChildPropertiesData(NodeData - parent).</emphasis></entry> - </row> - - <row> - <entry>getReferencesData</entry> - - <entry>This is the alias for the method - <emphasis>getReferencesData(String - nodeIdentifier).</emphasis></entry> - </row> - - <row> - <entry>commit</entry> - - <entry>This is the alias for the method - <emphasis>commit().</emphasis></entry> - </row> - - <row> - <entry>addNodeData</entry> - - <entry>This is the alias for the method <emphasis>add(NodeData - data).</emphasis></entry> - </row> - - <row> - <entry>addPropertyData</entry> - - <entry>This is the alias for the method <emphasis>add(PropertyData - data).</emphasis></entry> - </row> - - <row> - <entry>updateNodeData</entry> - - <entry>This is the alias for the method <emphasis>update(NodeData - data).</emphasis></entry> - </row> - - <row> - <entry>updatePropertyData</entry> - - <entry>This is the alias for the method - <emphasis>update(PropertyData data).</emphasis></entry> - </row> - - <row> - <entry>deleteNodeData</entry> - - <entry>This is the alias for the method <emphasis>delete(NodeData - data).</emphasis></entry> - </row> - - <row> - <entry>deletePropertyData</entry> - - <entry>This is the alias for the method - <emphasis>delete(PropertyData data).</emphasis></entry> - </row> - - <row> - <entry>renameNodeData</entry> - - <entry>This is the alias for the method <emphasis>rename(NodeData - data).</emphasis></entry> - </row> - - <row> - <entry>rollback</entry> - - <entry>This is the alias for the method - <emphasis>rollback().</emphasis></entry> - </row> - - <row> - <entry>isOpened</entry> - - <entry>This is the alias for the method - <emphasis>isOpened().</emphasis></entry> - </row> - - <row> - <entry>close</entry> - - <entry>This is the alias for the method - <emphasis>close().</emphasis></entry> - </row> - </tbody> - </tgroup> - </table> - </section> - - <section> - <title>Statistics on the JCR API accesses</title> - - <para>In order to know exactly how your application uses eXo JCR, it cans - be interesting to register all the JCR API accesses in order to easily - create real life test scenario based on pure JCR calls and also to tune - your eXo JCR to better fit your requirements.</para> - - <para>In order to allow you to specify into the configuration which part - of eXo JCR needs to be monitored whitout applying any changes in your code - and/or building anything, we choosed to rely on the Load-time Weaving - proposed by AspectJ.</para> - - <para>To enable this feature, you will have to add in your classpath the - following jar files:</para> - - <itemizedlist> - <listitem> - <para><emphasis>exo.jcr.component.statistics-X.Y.Z</emphasis>.jar - corresponding to your eXo JCR version that you can get from the jboss - maven repository <ulink - url="http://repository.jboss.com/maven2/org/exoplatform/jcr/exo.jcr.... - </listitem> - - <listitem> - <para>aspectjrt-1.6.8.jar that you can get from the main maven - repository <ulink - url="http://repo2.maven.org/maven2/org/aspectj/aspectjrt">&l... - </listitem> - </itemizedlist> - - <para>You will also need to get aspectjweaver-1.6.8.jar from the main - maven repository <ulink - url="http://repo2.maven.org/maven2/org/aspectj/aspectjweaver"&g...;. - At this stage, to enable the statistics on the JCR API accesses, you will - need to add the JVM parameter - <emphasis>-javaagent:${pathto}/aspectjweaver-1.6.8.jar</emphasis> to your - command line, for more details please refer to <ulink - url="http://www.eclipse.org/aspectj/doc/released/devguide/ltw-config... - - <para>By default, the configuration will collect statistcs on all the - methods of the internal interfaces - <emphasis>org.exoplatform.services.jcr.core.ExtendedSession</emphasis> and - <emphasis>org.exoplatform.services.jcr.core.ExtendedNode</emphasis>, and - the JCR API interface <emphasis>javax.jcr.Property</emphasis>. To add - and/or remove some interfaces to monitor, you have two configuration files - to change that are bundled into the jar - <emphasis>exo.jcr.component.statistics-X.Y.Z</emphasis>.jar, which are - <emphasis>conf/configuration.xml</emphasis> and - <emphasis>META-INF/aop.xml</emphasis>.</para> - - <para>The file content below is the content of - <emphasis>conf/configuration.xml</emphasis> that you will need to modify - to add and/or remove the full qualified name of the interfaces to monitor, - into the list of parameter values of the init param called - <emphasis>targetInterfaces</emphasis>.</para> - - <programlisting>&lt;configuration xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.exoplaform.org/xml/ns/kernel_1_0.xsd http://www.exoplaform.org/xml/ns/kernel_1_0.xsd" - xmlns="http://www.exoplaform.org/xml/ns/kernel_1_0.xsd"&gt; - - &lt;component&gt; - &lt;type&gt;org.exoplatform.services.jcr.statistics.JCRAPIAspectConfig&lt;/type&gt; - &lt;init-params&gt; - &lt;values-param&gt; - &lt;name&gt;targetInterfaces&lt;/name&gt; - &lt;value&gt;org.exoplatform.services.jcr.core.ExtendedSession&lt;/value&gt; - &lt;value&gt;org.exoplatform.services.jcr.core.ExtendedNode&lt;/value&gt; - &lt;value&gt;javax.jcr.Property&lt;/value&gt; - &lt;/values-param&gt; - &lt;/init-params&gt; - &lt;/component&gt; -&lt;/configuration&gt;</programlisting> - - <para>The file content below is the content of - <emphasis>META-INF/aop.xml</emphasis> that you will to need to modify to - add and/or remove the full qualified name of the interfaces to monitor, - into the expression filter of the pointcut called - <emphasis>JCRAPIPointcut</emphasis>. As you can see below, by default only - JCR API calls from the exoplatform packages are took into account, don't - hesistate to modify also this filter to add your own package names.</para> - - <programlisting>&lt;aspectj&gt; - &lt;aspects&gt; - &lt;concrete-aspect name="org.exoplatform.services.jcr.statistics.JCRAPIAspectImpl" extends="org.exoplatform.services.jcr.statistics.JCRAPIAspect"&gt; - &lt;pointcut name="JCRAPIPointcut" - expression="(target(org.exoplatform.services.jcr.core.ExtendedSession) || target(org.exoplatform.services.jcr.core.ExtendedNode) || target(javax.jcr.Property)) &amp;amp;&amp;amp; call(public * *(..))" /&gt; - &lt;/concrete-aspect&gt; - &lt;/aspects&gt; - &lt;weaver options="-XnoInline"&gt; - &lt;include within="org.exoplatform..*" /&gt; - &lt;/weaver&gt; -&lt;/aspectj&gt; </programlisting> - - <para>The corresponding CSV files are of type - <emphasis>Statistics${interface-name}-${creation-timestamp}.csv</emphasis> - for more details about how the csv files are managed please refer to the - section dedicated to the statistics manager.</para> - - <para>The format of each column header is ${method-alias}-${metric-alias}. - The method alias will be of type ${method-name}(list of parameter types - separeted by ; to be compatible with the CSV format).</para> - - <para>The metric alias are described in the statistics manager - section.</para> - - <remark>Please note that this feature will affect the performances of eXo - JCR so it must be used with caution.</remark> - </section> - - <section> - <title>Statistics Manager</title> - - <para>The statistics manager manages all the statistics provided by eXo - JCR, it is responsible of printing the data into the CSV files but also to - expose the statistics through JMX and/or Rest.</para> - - <para>The statistics manager will create all the CSV files for each - category of statistics that it manages, the format of those files is - <emphasis>Statistics${category-name}-${creation-timestamp}.csv</emphasis>. - Those files will be created into the user directory if it is possible - otherwise it will create them into the temporary directory. The format of - those files is <envar>CSV</envar> (i.e. Comma-Seperated Values), one new - line will be added regularily (every 5 seconds by default) and one last - line will be added at JVM exit. Each line, will be composed of the 5 - figures described below for each method and globaly for all the - methods.</para> - - <para><table> - <title>Metric Alias</title> - - <tgroup cols="2"> - <tbody> - <row> - <entry>Min</entry> - - <entry>The minimum time spent into the method.</entry> - </row> - - <row> - <entry>Max</entry> - - <entry>The maximum time spent into the method.</entry> - </row> - - <row> - <entry>Total</entry> - - <entry>The total amount of time spent into the method.</entry> - </row> - - <row> - <entry>Avg</entry> - - <entry>The average time spent into the method.</entry> - </row> - - <row> - <entry>Times</entry> - - <entry>The total amount of times the method has been - called.</entry> - </row> - </tbody> - </tgroup> - </table>You can disable the persistence of the statistics by setting the - JVM parameter called - <emphasis>JCRStatisticsManager.persistence.enabled</emphasis> to - <emphasis>false</emphasis>, by default it is set to - <emphasis>true</emphasis>. You can aslo define the period of time between - each record (i.e. line of data into the file) by setting the JVM parameter - called <emphasis>JCRStatisticsManager.persistence.timeout</emphasis> to - your expected value expressed in milliseconds, by default it is set to - <emphasis>5000</emphasis>.</para> - - <para>You can also access to the statistics thanks to JMX, the available - methods are the following:</para> - - <para><table> - <title>JMX Methods</title> - - <tgroup cols="2"> - <tbody> - <row> - <entry>getMin</entry> - - <entry>Gives the minimum time spent into the method - corresponding to the given category name and statistics name. - The expected arguments are the name of the category of the - statistics (e.g. JDBCStorageConnection) and the name of the - expected method or global for the global value.</entry> - </row> - - <row> - <entry>getMax</entry> - - <entry>Gives the maximum time spent into the method - corresponding to the given category name and statistics name. - The expected arguments are the name of the category of the - statistics (e.g. JDBCStorageConnection) and the name of the - expected method or global for the global value.</entry> - </row> - - <row> - <entry>getTotal</entry> - - <entry>Gives the total amount of time spent into the method - corresponding to the given category name and statistics name. - The expected arguments are the name of the category of the - statistics (e.g. JDBCStorageConnection) and the name of the - expected method or global for the global value.</entry> - </row> - - <row> - <entry>getAvg</entry> - - <entry>Gives the average time spent into the method - corresponding to the given category name and statistics name. - The expected arguments are the name of the category of the - statistics (e.g. JDBCStorageConnection) and the name of the - expected method or global for the global value.</entry> - </row> - - <row> - <entry>getTimes</entry> - - <entry>Gives the total amount of times the method has been - called corresponding to the given category name and statistics - name. The expected arguments are the name of the category of the - statistics (e.g. JDBCStorageConnection) and the name of the - expected method or global for the global value.</entry> - </row> - - <row> - <entry>reset</entry> - - <entry>Reset the statistics for the given category name and - statistics name. The expected arguments are the name of the - category of the statistics (e.g. JDBCStorageConnection) and the - name of the expected method or global for the global - value.</entry> - </row> - - <row> - <entry>resetAll</entry> - - <entry>Reset all the statistics for the given category name. The - expected argument is the name of the category of the statistics - (e.g. JDBCStorageConnection).</entry> - </row> - </tbody> - </tgroup> - </table>The full name of the related MBean is - <emphasis>exo:service=statistic, view=jcr</emphasis>.</para> - </section> -</chapter> +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" +"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> +<chapter id="JCR.Statistics"> + <?dbhtml filename="ch-statistics.html"?> + + <title>eXo JCR statistics</title> + + <section> + <title>Statistics on the Database Access Layer</title> + + <para>In order to have a better idea of the time spent into the database + access layer, it cans be interesting to get some statistics on that part + of the code, knowing that most of the time spent into eXo JCR is mainly + the database access. This statistics will then allow you to identify + without using any profiler what is anormally slow in this layer, which + could help to fix the problem quickly.</para> + + <para>In case you use + <envar>org.exoplatform.services.jcr.impl.storage.jdbc.optimisation.CQJDBCWorkspaceDataContainer</envar> + or + <envar>org.exoplatform.services.jcr.impl.storage.jdbc.JDBCWorkspaceDataContainer</envar> + as <envar>WorkspaceDataContainer</envar>, you can get statistics on the + time spent into the database access layer. The database access layer (in + eXo JCR) is represented by the methods of the interface + <envar>org.exoplatform.services.jcr.storage.WorkspaceStorageConnection</envar>, + so for all the methods defined in this interface, we can have the + following figures:</para> + + <itemizedlist> + <listitem> + <para>The minimum time spent into the method.</para> + </listitem> + + <listitem> + <para>The maximum time spent into the method.</para> + </listitem> + + <listitem> + <para>The average time spent into the method.</para> + </listitem> + + <listitem> + <para>The total amount of time spent into the method.</para> + </listitem> + + <listitem> + <para>The total amount of times the method has been called.</para> + </listitem> + </itemizedlist> + + <para>Those figures are also available globaly for all the methods which + gives us the global behavior of this layer.</para> + + <para>If you want to enable the statistics, you just need to set the JVM + parameter called + <emphasis>JDBCWorkspaceDataContainer.statistics.enabled</emphasis> to + <emphasis>true</emphasis>. The corresponding CSV file is + <emphasis>StatisticsJDBCStorageConnection-${creation-timestamp}.csv</emphasis> + for more details about how the csv files are managed please refer to the + section dedicated to the statistics manager.</para> + + <para>The format of each column header is ${method-alias}-${metric-alias}. + The metric alias are described in the statistics manager section.</para> + + <table> + <title>Method Alias</title> + + <tgroup cols="2"> + <tbody> + <row> + <entry>global</entry> + + <entry>This is the alias for all the methods.</entry> + </row> + + <row> + <entry>getItemDataById</entry> + + <entry>This is the alias for the method + <emphasis>getItemData(String identifier).</emphasis></entry> + </row> + + <row> + <entry>getItemDataByNodeDataNQPathEntry</entry> + + <entry>This is the alias for the method + <emphasis>getItemData(NodeData parentData, QPathEntry + name).</emphasis></entry> + </row> + + <row> + <entry>getChildNodesData</entry> + + <entry>This is the alias for the method + <emphasis>getChildNodesData(NodeData parent).</emphasis></entry> + </row> + + <row> + <entry>getChildNodesCount</entry> + + <entry>This is the alias for the method + <emphasis>getChildNodesCount(NodeData parent).</emphasis></entry> + </row> + + <row> + <entry>getChildPropertiesData</entry> + + <entry>This is the alias for the method + <emphasis>getChildPropertiesData(NodeData + parent).</emphasis></entry> + </row> + + <row> + <entry>listChildPropertiesData</entry> + + <entry>This is the alias for the method + <emphasis>listChildPropertiesData(NodeData + parent).</emphasis></entry> + </row> + + <row> + <entry>getReferencesData</entry> + + <entry>This is the alias for the method + <emphasis>getReferencesData(String + nodeIdentifier).</emphasis></entry> + </row> + + <row> + <entry>commit</entry> + + <entry>This is the alias for the method + <emphasis>commit().</emphasis></entry> + </row> + + <row> + <entry>addNodeData</entry> + + <entry>This is the alias for the method <emphasis>add(NodeData + data).</emphasis></entry> + </row> + + <row> + <entry>addPropertyData</entry> + + <entry>This is the alias for the method <emphasis>add(PropertyData + data).</emphasis></entry> + </row> + + <row> + <entry>updateNodeData</entry> + + <entry>This is the alias for the method <emphasis>update(NodeData + data).</emphasis></entry> + </row> + + <row> + <entry>updatePropertyData</entry> + + <entry>This is the alias for the method + <emphasis>update(PropertyData data).</emphasis></entry> + </row> + + <row> + <entry>deleteNodeData</entry> + + <entry>This is the alias for the method <emphasis>delete(NodeData + data).</emphasis></entry> + </row> + + <row> + <entry>deletePropertyData</entry> + + <entry>This is the alias for the method + <emphasis>delete(PropertyData data).</emphasis></entry> + </row> + + <row> + <entry>renameNodeData</entry> + + <entry>This is the alias for the method <emphasis>rename(NodeData + data).</emphasis></entry> + </row> + + <row> + <entry>rollback</entry> + + <entry>This is the alias for the method + <emphasis>rollback().</emphasis></entry> + </row> + + <row> + <entry>isOpened</entry> + + <entry>This is the alias for the method + <emphasis>isOpened().</emphasis></entry> + </row> + + <row> + <entry>close</entry> + + <entry>This is the alias for the method + <emphasis>close().</emphasis></entry> + </row> + </tbody> + </tgroup> + </table> + </section> + + <section> + <title>Statistics on the JCR API accesses</title> + + <para>In order to know exactly how your application uses eXo JCR, it cans + be interesting to register all the JCR API accesses in order to easily + create real life test scenario based on pure JCR calls and also to tune + your eXo JCR to better fit your requirements.</para> + + <para>In order to allow you to specify into the configuration which part + of eXo JCR needs to be monitored whitout applying any changes in your code + and/or building anything, we choosed to rely on the Load-time Weaving + proposed by AspectJ.</para> + + <para>To enable this feature, you will have to add in your classpath the + following jar files:</para> + + <itemizedlist> + <listitem> + <para><emphasis>exo.jcr.component.statistics-X.Y.Z</emphasis>.jar + corresponding to your eXo JCR version that you can get from the jboss + maven repository <ulink + url="http://repository.jboss.com/maven2/org/exoplatform/jcr/exo.jcr.... + </listitem> + + <listitem> + <para>aspectjrt-1.6.8.jar that you can get from the main maven + repository <ulink + url="http://repo2.maven.org/maven2/org/aspectj/aspectjrt">&l... + </listitem> + </itemizedlist> + + <para>You will also need to get aspectjweaver-1.6.8.jar from the main + maven repository <ulink + url="http://repo2.maven.org/maven2/org/aspectj/aspectjweaver"&g...;. + At this stage, to enable the statistics on the JCR API accesses, you will + need to add the JVM parameter + <emphasis>-javaagent:${pathto}/aspectjweaver-1.6.8.jar</emphasis> to your + command line, for more details please refer to <ulink + url="http://www.eclipse.org/aspectj/doc/released/devguide/ltw-config... + + <para>By default, the configuration will collect statistcs on all the + methods of the internal interfaces + <emphasis>org.exoplatform.services.jcr.core.ExtendedSession</emphasis> and + <emphasis>org.exoplatform.services.jcr.core.ExtendedNode</emphasis>, and + the JCR API interface <emphasis>javax.jcr.Property</emphasis>. To add + and/or remove some interfaces to monitor, you have two configuration files + to change that are bundled into the jar + <emphasis>exo.jcr.component.statistics-X.Y.Z</emphasis>.jar, which are + <emphasis>conf/configuration.xml</emphasis> and + <emphasis>META-INF/aop.xml</emphasis>.</para> + + <para>The file content below is the content of + <emphasis>conf/configuration.xml</emphasis> that you will need to modify + to add and/or remove the full qualified name of the interfaces to monitor, + into the list of parameter values of the init param called + <emphasis>targetInterfaces</emphasis>.</para> + + <programlisting>&lt;configuration xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.exoplaform.org/xml/ns/kernel_1_0.xsd http://www.exoplaform.org/xml/ns/kernel_1_0.xsd" + xmlns="http://www.exoplaform.org/xml/ns/kernel_1_0.xsd"&gt; + + &lt;component&gt; + &lt;type&gt;org.exoplatform.services.jcr.statistics.JCRAPIAspectConfig&lt;/type&gt; + &lt;init-params&gt; + &lt;values-param&gt; + &lt;name&gt;targetInterfaces&lt;/name&gt; + &lt;value&gt;org.exoplatform.services.jcr.core.ExtendedSession&lt;/value&gt; + &lt;value&gt;org.exoplatform.services.jcr.core.ExtendedNode&lt;/value&gt; + &lt;value&gt;javax.jcr.Property&lt;/value&gt; + &lt;/values-param&gt; + &lt;/init-params&gt; + &lt;/component&gt; +&lt;/configuration&gt;</programlisting> + + <para>The file content below is the content of + <emphasis>META-INF/aop.xml</emphasis> that you will to need to modify to + add and/or remove the full qualified name of the interfaces to monitor, + into the expression filter of the pointcut called + <emphasis>JCRAPIPointcut</emphasis>. As you can see below, by default only + JCR API calls from the exoplatform packages are took into account, don't + hesistate to modify also this filter to add your own package names.</para> + + <programlisting>&lt;aspectj&gt; + &lt;aspects&gt; + &lt;concrete-aspect name="org.exoplatform.services.jcr.statistics.JCRAPIAspectImpl" extends="org.exoplatform.services.jcr.statistics.JCRAPIAspect"&gt; + &lt;pointcut name="JCRAPIPointcut" + expression="(target(org.exoplatform.services.jcr.core.ExtendedSession) || target(org.exoplatform.services.jcr.core.ExtendedNode) || target(javax.jcr.Property)) &amp;amp;&amp;amp; call(public * *(..))" /&gt; + &lt;/concrete-aspect&gt; + &lt;/aspects&gt; + &lt;weaver options="-XnoInline"&gt; + &lt;include within="org.exoplatform..*" /&gt; + &lt;/weaver&gt; +&lt;/aspectj&gt; </programlisting> + + <para>The corresponding CSV files are of type + <emphasis>Statistics${interface-name}-${creation-timestamp}.csv</emphasis> + for more details about how the csv files are managed please refer to the + section dedicated to the statistics manager.</para> + + <para>The format of each column header is ${method-alias}-${metric-alias}. + The method alias will be of type ${method-name}(list of parameter types + separeted by ; to be compatible with the CSV format).</para> + + <para>The metric alias are described in the statistics manager + section.</para> + + <remark>Please note that this feature will affect the performances of eXo + JCR so it must be used with caution.</remark> + </section> + + <section> + <title>Statistics Manager</title> + + <para>The statistics manager manages all the statistics provided by eXo + JCR, it is responsible of printing the data into the CSV files but also to + expose the statistics through JMX and/or Rest.</para> + + <para>The statistics manager will create all the CSV files for each + category of statistics that it manages, the format of those files is + <emphasis>Statistics${category-name}-${creation-timestamp}.csv</emphasis>. + Those files will be created into the user directory if it is possible + otherwise it will create them into the temporary directory. The format of + those files is <envar>CSV</envar> (i.e. Comma-Seperated Values), one new + line will be added regularily (every 5 seconds by default) and one last + line will be added at JVM exit. Each line, will be composed of the 5 + figures described below for each method and globaly for all the + methods.</para> + + <para><table> + <title>Metric Alias</title> + + <tgroup cols="2"> + <tbody> + <row> + <entry>Min</entry> + + <entry>The minimum time spent into the method.</entry> + </row> + + <row> + <entry>Max</entry> + + <entry>The maximum time spent into the method.</entry> + </row> + + <row> + <entry>Total</entry> + + <entry>The total amount of time spent into the method.</entry> + </row> + + <row> + <entry>Avg</entry> + + <entry>The average time spent into the method.</entry> + </row> + + <row> + <entry>Times</entry> + + <entry>The total amount of times the method has been + called.</entry> + </row> + </tbody> + </tgroup> + </table>You can disable the persistence of the statistics by setting the + JVM parameter called + <emphasis>JCRStatisticsManager.persistence.enabled</emphasis> to + <emphasis>false</emphasis>, by default it is set to + <emphasis>true</emphasis>. You can aslo define the period of time between + each record (i.e. line of data into the file) by setting the JVM parameter + called <emphasis>JCRStatisticsManager.persistence.timeout</emphasis> to + your expected value expressed in milliseconds, by default it is set to + <emphasis>5000</emphasis>.</para> + + <para>You can also access to the statistics thanks to JMX, the available + methods are the following:</para> + + <para><table> + <title>JMX Methods</title> + + <tgroup cols="2"> + <tbody> + <row> + <entry>getMin</entry> + + <entry>Gives the minimum time spent into the method + corresponding to the given category name and statistics name. + The expected arguments are the name of the category of the + statistics (e.g. JDBCStorageConnection) and the name of the + expected method or global for the global value.</entry> + </row> + + <row> + <entry>getMax</entry> + + <entry>Gives the maximum time spent into the method + corresponding to the given category name and statistics name. + The expected arguments are the name of the category of the + statistics (e.g. JDBCStorageConnection) and the name of the + expected method or global for the global value.</entry> + </row> + + <row> + <entry>getTotal</entry> + + <entry>Gives the total amount of time spent into the method + corresponding to the given category name and statistics name. + The expected arguments are the name of the category of the + statistics (e.g. JDBCStorageConnection) and the name of the + expected method or global for the global value.</entry> + </row> + + <row> + <entry>getAvg</entry> + + <entry>Gives the average time spent into the method + corresponding to the given category name and statistics name. + The expected arguments are the name of the category of the + statistics (e.g. JDBCStorageConnection) and the name of the + expected method or global for the global value.</entry> + </row> + + <row> + <entry>getTimes</entry> + + <entry>Gives the total amount of times the method has been + called corresponding to the given category name and statistics + name. The expected arguments are the name of the category of the + statistics (e.g. JDBCStorageConnection) and the name of the + expected method or global for the global value.</entry> + </row> + + <row> + <entry>reset</entry> + + <entry>Reset the statistics for the given category name and + statistics name. The expected arguments are the name of the + category of the statistics (e.g. JDBCStorageConnection) and the + name of the expected method or global for the global + value.</entry> + </row> + + <row> + <entry>resetAll</entry> + + <entry>Reset all the statistics for the given category name. The + expected argument is the name of the category of the statistics + (e.g. JDBCStorageConnection).</entry> + </row> + </tbody> + </tgroup> + </table>The full name of the related MBean is + <emphasis>exo:service=statistic, view=jcr</emphasis>.</para> + </section> +</chapter>