[jbpm-commits] JBoss JBPM SVN: r6212 - in jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en: modules and 1 other directory.

Author: alex.guizar(a)jboss.com Date: 2010-03-08 06:35:50 -0500 (Mon, 08 Mar 2010) New Revision: 6212 Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en/images/create_connection.png jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en/images/execute_script.png jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en/images/load_script.png Removed: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en/images/create_connection.jpg jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en/images/execute_script.jpg jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en/images/install_driver.jpg jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en/images/load_script.jpg Modified: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en/modules/database.xml jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en/modules/persistence.xml Log: JBPM-2164: Document JbpmSchema API and Ant task Deleted: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en/images/create_connection.jpg =================================================================== (Binary files differ) Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en/images/create_connection.png =================================================================== (Binary files differ) Property changes on: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en/images/create_connection.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Deleted: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en/images/execute_script.jpg =================================================================== (Binary files differ) Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en/images/execute_script.png =================================================================== (Binary files differ) Property changes on: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en/images/execute_script.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Deleted: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en/images/install_driver.jpg =================================================================== (Binary files differ) Deleted: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en/images/load_script.jpg =================================================================== (Binary files differ) Added: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en/images/load_script.png =================================================================== (Binary files differ) Property changes on: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en/images/load_script.png ___________________________________________________________________ Name: svn:mime-type + application/octet-stream Modified: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en/modules/database.xml =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en/modules/database.xml 2010-03-05 08:17:30 UTC (rev 6211) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en/modules/database.xml 2010-03-08 11:35:50 UTC (rev 6212) @@ -22,7 +22,7 @@ location on your machine named ${jbpm-jpdl-home}. You will find the DB subproject of jBPM in the ${jbpm-jpdl-home}/db.</para> - <para>After installing the of your choice database, you will have to run + <para>After installing the database of your choice, you will have to run the database creation scripts to create the jBPM tables. Note that in the hsqldb inside jboss this is done automatically during installation. </para> @@ -30,7 +30,7 @@ <title>Isolation level</title> <para>Whatever database that you use, make sure that the isolation level of the configured JDBC connection is at least READ_COMMITTED, as explained - in <xref linkend="isolationlevelofthejdbcconnection"/> + in <xref linkend="isolationlevelofthejdbcconnection"/>. </para> </section> @@ -57,29 +57,14 @@ </mediaobject> </figure> - <para>After the installation of the database, we can use a database - viewer tool like DBVisualizer to look at the contents of the database. - Before you can define a database connection with DBVisualizer, you might - have to add the PostgreSQL JDBC driver to the driver manager. Select - 'Tools-&gt;Driver Manager...' to open the driver manager window. Look at - the figure below for an example of how to add the PostgreSQL JDBC - driver.</para> + <para>After the installation of the database, we can use the pgAdmin III + Query tool to look at the contents of the database.</para> - <figure> - <title>Adding the JDBC driver to the driver manager</title> - - <mediaobject> - <imageobject> - <imagedata fileref="images/install_driver.jpg" /> - </imageobject> - </mediaobject> - </figure> - - <para>Now everything is set to define a database connection in - DBVisualizer to our newly created database. We will use this tool + <para>Before we do, we have to define a database connection in + pgAdmin to our newly created database. We will use this tool further in this document to make sure the creation scripts and process deployment are working as expected. For an example of creating the - connection in DBVisualizer we refer to the following figure. As you can + connection in pgAdmin we refer to the following figure. As you will see, there are no tables present yet in this database. We will create them in the following section.</para> @@ -88,7 +73,7 @@ <mediaobject> <imageobject> - <imagedata fileref="images/create_connection.jpg" /> + <imagedata fileref="images/create_connection.png" /> </imageobject> </mediaobject> </figure> @@ -120,7 +105,7 @@ </section> <section> - <title>Creating the JBoss jBPM Database with your new PostGreSQL or + <title>Creating the JBoss jBPM Database with your new PostgreSQL or MySQL</title> <para>In order to get the proper database scripts for your @@ -128,19 +113,19 @@ Using your database admin console, navigate to the database and then open and execute the create script we just referenced. Below are screen shots - doing this for PostGreSQL and MySQL under their respective admin + doing this for PostgreSQL and MySQL under their respective admin consoles</para> <section> - <title>Creating the JBoss jBPM Database with PostGreSQL</title> + <title>Creating the jBPM Database with PostgreSQL</title> <para>As already mentioned you will find the database scripts for a lot of the supported databases in the DB subproject. The database scripts for PostgreSQL are found in the folder '${jbpm-jpdl-home}/db. The creation script is - called 'postgresql.create.sql'. Using DBVisualizer, you can load this - script by switching to the 'SQL Commander' tab and then selecting - 'File-&gt;Load...'. In the following dialog, navigate to the creation + called 'postgresql.create.sql'. Using pgAdmin, you can load this + script by selecting 'Tools-&gt;Query tool' and then + 'File-&gt;Open...'. In the following dialog, navigate to the creation script file. The result of doing so is shown in the figure below.</para> @@ -149,13 +134,13 @@ <mediaobject> <imageobject> - <imagedata fileref="images/load_script.jpg" /> + <imagedata fileref="images/load_script.png" /> </imageobject> </mediaobject> </figure> - <para>To execution this script with DBVisualizer, you select - 'Database-&gt;Execute'. After this step all JBoss jBPM tables are + <para>To execute this script with the pgAdmin Query tool, select + 'Query-&gt;Execute'. After this step all JBoss jBPM tables are created. The situation is illustrated in the figure below.</para> <figure> @@ -163,7 +148,7 @@ <mediaobject> <imageobject> - <imagedata fileref="images/execute_script.jpg" /> + <imagedata fileref="images/execute_script.png" /> </imageobject> </mediaobject> </figure> @@ -191,14 +176,14 @@ scripts. Open a DOS box or terminal window and type the following command:</para> - <programlisting> mysql -u root -p </programlisting> + <screen>$ mysql -u root -p </screen> <para>You will be prompted for your MySQL password for the root account or whatever account you are using to modify this database. After logging in, type the following command to use the newly created jbpmdb:</para> - <programlisting>use jbpmdb </programlisting> + <screen>use jbpmdb </screen> <figure> <title>Loading the database create scripts for MySQL</title> @@ -213,9 +198,9 @@ <para>Now you can load the database script for jBPM by executing the following command:</para> - <programlisting>source mysql.drop.create.sql </programlisting> + <screen>source mysql.drop.create.sql </screen> - <para>Once the script executes, you should have the folling output in + <para>Once the script executes, you should have the following output in the MySQL command window:</para> <figure> @@ -234,7 +219,7 @@ <title>Last Steps</title> <para>After these steps, there is not yet any data present in the - tables. For the jBPM webapp to work, you should at least create some + tables. For the jBPM web app to work, you should at least create some records in the jbpm_id_user table. In order to have exactly the same entries in this table as the default distribution of the starter's kit running on HSQLDB, we suggest to run the script below.</para> @@ -253,7 +238,7 @@ <title>Update the JBoss jBPM Server Configuration</title> <para>Before we can really use our newly created database with the JBoss - jBPM default webapp we will have to do some updates to the JBoss jBPM + jBPM default web app we will have to do some updates to the JBoss jBPM configuration. The location of the jbpm server configuration is <literal>${jboss-home}/server/default/deploy/jbpm</literal>. </para> @@ -282,9 +267,7 @@ <para>For MySQL, the datasource definition would look as follows:</para> - <programlisting>&lt;?xml version="1.0" encoding="UTF-8"?&gt; - -&lt;datasources&gt; + <programlisting language="xml">&lt;datasources&gt; &lt;local-tx-datasource&gt; &lt;jndi-name&gt;JbpmDS&lt;/jndi-name&gt; &lt;connection-url&gt;jdbc:mysql://localhost:3306/jbpmdb&lt;/connection-url&gt; @@ -304,10 +287,9 @@ you just created a new DataSource for your JBoss jBPM server. Well, almost... To make things really work you will have to copy the correct JDBC driver to the <literal>${jboss.home}/server/default/lib</literal> folder. - We already used this JDBC driver above when we were installing it in - DBVisualizer to be able to browse our newly created database. The file + The file is named <literal>postgresql-8.1-*.jdbc3.jar</literal> and it can be found in the jdbc - subfolder of your PostgreSQL installation folder.</para> + subdirectory of your PostgreSQL installation folder.</para> <para>For MySQL, copy the jdbc driver installed from the MySQL ConnectorJ package. The version you need to use is currently the MySQL @@ -331,13 +313,7 @@ using. You can get a list of supported database Dialect types from here http://www.hibernate.org/hib_docs/v3/reference/en/html/session-configurat... - <programlisting>&lt;?xml version='1.0' encoding='utf-8'?&gt; - -&lt;!DOCTYPE hibernate-configuration PUBLIC - "-//Hibernate/Hibernate Configuration DTD 3.0//EN" - "http://hibernate.sourceforge.net/hibernate-configuration-3.0.dtd"&gt; - -&lt;hibernate-configuration&gt; + <programlisting language="xml">&lt;hibernate-configuration&gt; &lt;session-factory&gt; &lt;!-- jdbc connection properties --&gt; @@ -360,7 +336,7 @@ &lt;/session-factory&gt; &lt;/hibernate-configuration&gt;</programlisting> - <para>Now we are ready to fire up the server, and look if the webapp + <para>Now we are ready to fire up the server, and look if the web app works. You will not be able to start any processes yet, as there are no processes deployed yet. To do this we refer to the document on process definition deployment.</para> Modified: jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en/modules/persistence.xml =================================================================== --- jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en/modules/persistence.xml 2010-03-05 08:17:30 UTC (rev 6211) +++ jbpm3/branches/jbpm-3.2-soa/modules/userguide/src/main/docbook/en/modules/persistence.xml 2010-03-08 11:35:50 UTC (rev 6212) @@ -501,7 +501,7 @@ store it on disk. </para> - <section id="isolationlevelofthejdbcconnection"> + <section id="jdbcconnectionisolation"> <title>Isolation level of the JDBC connection</title> <para>Make sure that the database isolation level that you configure for your JDBC connection is at least READ_COMMITTED. @@ -527,27 +527,114 @@ </itemizedlist> </section> - <section id="thejbpmdbschema"> - <title>The jBPM DB schema</title> - <para>The jbpm.db subproject, contains a number of drivers, instructions and - scripts to help you getting started on your database of choice. Please, - refer to the readme.html in the root of the jbpm.db project for more - information. + <section id="jbpmdbschema"> + <title>The jBPM database schema</title> + <para>The <literal>database</literal> and <literal>config</literal> directories + in the distribution contain scripts and Hibernate configuration files + to help you get started on your choice database. </para> - <para>While jBPM is capable of generating DDL scripts for all database, these - schemas are not always optimized. So you might want to have your DBA review + <para>While jBPM is capable of generating DDL scripts for any database + supported by Hibernate, the resulting + schemas are not always optimized. You might want to have your DBA review the DDL that is generated to optimize the column types and use of indexes. </para> <para>In development you might be interested in the following hibernate configuration: - If you set hibernate configuration property 'hibernate.hbm2ddl.auto' to 'create-drop' - (e.g. in the hibernate.cfg.xml), the schema will be automatically created in the - database the first time it is used in an application. When the application closes + If you set hibernate configuration property <literal>hibernate.hbm2ddl.auto</literal> + to <literal>create-drop</literal> in the Hibernate configuration file, + the database schema will be automatically created + the first time the application accesses the database. When the application closes down, the schema will be dropped. </para> - <para>The schema generation can also be invoked programmatically with - <literal>jbpmConfiguration.createSchema()</literal> and - <literal>jbpmConfiguration.dropSchema()</literal>. - </para> + <section id="programmaticdbschema"> + <title>Programmatic database schema operations</title> + <para>jBPM provides an API for creating and droping the database schema + through the <ulink + url="http://docs.jboss.com/jbpm/v3.2/javadoc-jpdl/org/jbpm/JbpmConfi... + <classname>org.jbpm.JbpmConfiguration</classname></ulink> methods + <methodname>createSchema</methodname> and <methodname>dropSchema</methodname>. + Be aware that there is no constraint on invoking these methods other than + the privileges of the configured database user. + </para> + <para>The aforementioned APIs constitute a facade to the broader functionality + offered by class <ulink + url="http://docs.jboss.com/jbpm/v3.2/javadoc-jpdl/org/jbpm/db/JbpmSc... + <classname>org.jbpm.db.JbpmSchema</classname></ulink>: + </para> + <itemizedlist> + <listitem>Create, drop, update and clean (drop-create) the database schema</listitem> + <listitem>Generate SQL scripts for the above operations</listitem> + <listitem>List the mapped tables and query the existing tables in the database</listitem> + </itemizedlist> + </section> + <section id="jbpmschematask"> + <title>The jBPM schema Ant task</title> + <para>As an alternative to programmatic schema manipulation, jBPM provides an Ant task + for generating scripts that create, drop and update the database schema. + The listing below illustrates the task being used to generate the schema + creation script and save it to file <literal>create.sql</literal>. The Hibernate + configuration is read from the resource <literal>hibernate.cfg.xml</literal>.</para> + <programlisting><![CDATA[<taskdef name="jbpmschema" classname="org.jbpm.ant.JbpmSchemaTask"> + <classpath> + <pathelement location="jbpm-jpdl.jar" /> + <pathelement location="hibernate.jar" /> + <pathelement location="dom4j.jar" /> + <pathelement location="commons-logging.jar"/> + <pathelement location="commons-collections.jar"/> + </classpath> +</taskdef> + +<jbpmschema config="hibernate.cfg.xml" action="create" output="create.sql" />]]></programlisting> + <para>The task parameters are documented below.</para> + <table><title>jBPM schema task parameters</title><tgroup cols='3'> + <colspec colname='attr' colwidth="*" /> + <colspec colname='desc' colwidth="3*" /> + <colspec colname='req' colwidth="*" /> + <thead> + <row> + <entry>Attribute</entry> + <entry>Description</entry> + <entry>Required</entry> + </row> + </thead> + <tbody> + <row> + <entry>config</entry> + <entry>Hibernate configuration resource</entry> + <entry>No, default <literal>hibernate.cfg.xml</literal></entry> + </row> + <row> + <entry>properties</entry> + <entry>Hibernate properties resource. These properties override + property values from the <literal>config</literal> resource.</entry> + <entry>No</entry> + </row> + <row> + <entry>action</entry> + <entry>Database schema operation to script. Can be <literal>create</literal>, + <literal>drop</literal>, <literal>update</literal> or + <literal>clean</literal>.</entry> + <entry>No, default <literal>create</literal></entry> + </row> + <row> + <entry>output</entry> + <entry>The output file. The generated script is written to this file.</entry> + <entry>Yes</entry> + </row> + <row> + <entry>delimiter</entry> + <entry>String that separates SQL statements</entry> + <entry>No, default <literal>;</literal></entry> + </row> + <row> + <entry>delimiterType</entry> + <entry>Control whether the delimiter should be placed on a line by itself. + Can be <literal>normal</literal>, at the end of line, or <literal>row</literal>, + on a line by itself.</entry> + <entry>No, default <literal>normal</literal></entry> + </row> + </tbody> + </tgroup></table> + </section> </section> </section>