Author: tom.baeyens(a)jboss.com Date: 2008-11-09 07:01:09 -0500 (Sun, 09 Nov 2008) New Revision: 2829 Modified: jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/deployment.xml jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/gettingstarted.xml jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/introduction.xml jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/tutorial.xml Log: [1727] already some docs updates Modified: jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/deployment.xml =================================================================== --- jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/deployment.xml 2008-11-09 12:00:11 UTC (rev 2828) +++ jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/deployment.xml 2008-11-09 12:01:09 UTC (rev 2829) @@ -22,7 +22,7 @@ <section id="javaruntimeenvironment"> <title>Java runtime environment</title> - <para>jBPM 3 requires J2SE 1.4.2+ + <para>jBPM 3.3.x requires J2SE 1.5+ </para> </section> @@ -30,7 +30,8 @@ <title>Third party libraries</title> <para>All the libraries on which jPDL might have a dependency, are located in - the lib directory. + the lib directory. The actual version of those libraries might depend + on the JBoss server that you've selected in the installer. </para> <para>In a minimal deployment, you can create and run processes with jBPM @@ -98,7 +99,7 @@ </thead> <tbody> <row> - <entry>hibernate3.jar</entry> + <entry>hibernate.jar</entry> <entry>hibernate persistence</entry> <entry>the best O/R mapper</entry> </row> @@ -155,104 +156,16 @@ </tbody> </tgroup> </table> - </section> - <section id="libraryversions"> - <title>Library versions</title> - <para></para> - </section> - <section id="webapplication"> <title>Web application</title> - <para>In the deploy directory of the downloads, you can find - <emphasis role="bold">jbpm-console.war</emphasis>. That web console - contains the jPDL libraries, configuration files and the required libraries - to run this web application on JBoss. + <para>As part of the installation, the JSF based web application is installed + in JBoss in this location: </para> - <para><emphasis>This war file does NOT include the hibernate libraries.</emphasis> - That is because JBoss already includes the hibernate libraries. To run this web app - on other servers like Tomcat, all you have to do is get the hibernate libraries - in the <literal>WEB-INF/lib</literal> directory in the war file. Simplest - way to do that is to use the ant build script in this directory. - </para> - <para>Also, this war file can give you a good indication of how you could deploy - jbpm libraries and configuration files into your own web application. - </para> - <para>In the web app deployment descriptor, the <literal>JobExecutorLauncher</literal> - is configured. This will start the job executor when the web console - is deployed. The job executor serves as the basis for executing timers and - asynchronous messages on the standard java platform. - </para> + <para><literal>jboss-4.2.2.GA\server\default\deploy\jbpm\jbpm-enterprise-bundle.ear\jsf-console.war</literal></para> </section> - - <section id="enterprisearchive"> - <title>Enterprise archive</title> - - <para>In the deploy directory of the downloads, you can find - <emphasis role="bold">jbpm-enterprise.ear</emphasis>. That J2EE 1.4 compliant - enterprise archive includes: jPDL libraries, jBPM configuration files, the - jBPM web console, and a couple of enterprise beans. In this package, jBPM - is configured for usage in an application server like JBoss. The asynchronous - messaging service is here bound to JMS and the scheduler service is bound to the - EJB Timer Service. So here in this .ear file, no <literal>JobExecutor</literal> - is started. The persistence service is configured to participate in the overall - JTA transaction. - </para> - - <para>Within the enterprise archive there are the following files: - </para> - - <itemizedlist> - <listitem><literal>jbpm-console.war</literal>: the console web application, adapted - for J2EE integration - </listitem> - <listitem><literal>jbpm-enterprise.jar</literal>: the supporting enterprise beans - </listitem> - <listitem><literal>lib/jbpm-configs.jar</literal>: configuration files - </listitem> - <listitem><literal>lib/jbpm-identity.jar</literal>: identity component classes - </listitem> - <listitem><literal>lib/jbpm-jpdl.jar</literal>: standard jPDL classes - </listitem> - <listitem><literal>meta-inf/application.xml</literal>: J2EE app descriptor - </listitem> - </itemizedlist> - - <para><literal>jbpm-enterprise.jar</literal> contains the following EJB components: - </para> - - <itemizedlist> - <listitem><literal>CommandServiceBean</literal></listitem> - <listitem><literal>CommandListenerBean</literal></listitem> - <listitem><literal>JobListenerBean</literal></listitem> - <listitem><literal>TimerEntityBean</literal></listitem> - </itemizedlist> - - <para>These beans are J2EE 1.4 / EJB 2.1 compliant, to allow them to be deployed on a - variety of application servers. Note however that jBPM only provides deployment descriptors - for JBoss Application Server. All beans are deployed with the transaction-attribute - <emphasis>Required</emphasis>. The source for the EJB classes and interfaces is in - <literal>src/enterprise</literal> and the javadocs in <literal>doc/javadoc-enterprise</literal>. - A detailed description can be found in <xref linkend="enterprisebeans" />. - </para> - - <para><literal>jbpm-configs.jar</literal> contains the following files: - </para> - - <itemizedlist> - <listitem><literal>jbpm.cfg.xml</literal>: the jBPM configuration</listitem> - <listitem><literal>hibernate.cfg.xml</literal>: the Hibernate configuration</listitem> - <listitem><literal>jbpm.mail.templates.xml</literal>: the e-mail templates</listitem> - </itemizedlist> - - <para>Sections <xref linkend="enterprisejbpmconfig"/> and <xref - linkend="enterprisehibernateconfig"/> examine the enterprise-specific settings in the - first two files. The last file is described in <xref linkend="mailtemplates"/>.</para> - - </section> - <section id="theruntimeandsuite"> <title>The jPDL Runtime and Suite</title> Modified: jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/gettingstarted.xml =================================================================== --- jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/gettingstarted.xml 2008-11-09 12:00:11 UTC (rev 2828) +++ jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/gettingstarted.xml 2008-11-09 12:01:09 UTC (rev 2829) @@ -4,129 +4,44 @@ <para>This chapter takes you through the first steps of getting JBoss jBPM and provides the initial pointers to get up and running in no time.</para> - <section id="downloadablesoverview"> - <title>Downloadables Overview</title> - <para>Listed below are the different jBPM packages that are available today. - Each of these packages contains one or more downloadable files. Along with each of - these files goes a description of its contents and a pointer to any relevant - installation instructions if they are available. </para> - <para>All downloads described below can be found on - <ulink url="http://sourceforge.net/project/showfiles.php?group_id=70542&quo... - sourceforge jbpm downloads page</ulink>.</para> - - <section id="jpdl3"> - <title>jPDL 3</title> - - <para><ulink url="http://sourceforge.net/project/showfiles.php?group_id=70542&... - Download jBPM jPDL 3 at sourceforge.net</ulink>. This is the main distribution package containing the - core engine and a number of additional modules that you may need to work with jPDL. - </para> - - <itemizedlist> - <listitem> - <para id="jbpm-jpdl-suite.zip"><emphasis role="bold">The jPDL Suite (jbpm-jpdl-suite.zip):</emphasis> - The jPDL Suite is an extended runtime that includes the designer and the server. All of - these components are preconfigured to interoperate out-of-the-box. - If you want to get started with jBPM quickly, this is the file you want to download. - It contains all the other modules of this package plus the graphical designer in one single - download. Extract the zipped archive into a folder of your choice and read the file named 'readme.html' - for more info and further installation instructions. With this starters kit you can - immediately get started with the <xref linkend="tutorial" />. - </para> - </listitem> - <listitem> - <para id="jbpm-jpdl.zip"><emphasis role="bold">The jPDL Runtime Engine (jbpm-jpdl.zip):</emphasis> - The download contains the jBPM core library, documentation and dependent libraries, as well as the - identity component for actor and group management. To start working with it, extract the archive - into a folder of your choice. You will find pointers to the User's Guide and other important - information resources in the 'readme.html' file in the 'jbpm-&lt;version&gt;' folder. - </para> - </listitem> - </itemizedlist> - </section> - - <section id="packagejpdlprocessdesigner"> - <title>jPDL Process Designer</title> - - <para><ulink url="http://sourceforge.net/project/showfiles.php?group_id=70542&... - The jPDL Suite package contains the jPDL process designer. You typically will download it in that - package. But you can also download JBoss jBPM Process Designer separate at sourceforge.net</ulink>. The - designer is an eclipse plugin and enables you to author your process definitions and to easily deploy them. - The plug-in is available for download either as a zipped Eclipse feature or as a zipped Eclipse update site. - There is no difference in content, the only difference is in the way you have to do the installation.</para> - - <itemizedlist> - <listitem> - <para id="jbpm-gpd-site-version.zip"><emphasis role="bold">Eclipse Update Site (jbpm-gpd-site-&lt;version&gt;.zip):</emphasis> - If you want to be absolutely sure that the designer installation goes smoothly, we recommend to use - the update site mechanism together with a new Eclipse installation. Of cource the Eclipse version - should match the downloaded update site archive. To get started with the designer plugin, follow the instructions - in the 'readme.html' file included in the archives root folder to succesfully install the GPD. - </para> - </listitem> - <listitem> - <para id="jbpm-gpd-feature-version.zip"><emphasis role="bold">Eclipse Feature (jbpm-gpd-feature-&lt;version&gt;.zip):</emphasis> - If you are tired of each time having to do a fresh Eclipse installation and you are willing to - cope with some possible issues, you can try the feature download. In this case installation is as - easy as extracting the archive into your Eclipse installation (make sure the included 'plugins' - and 'features' folders end up in the same location of your Eclipse installation) overwriting the - files and folders with the same name that are possibly already present. This installation is - very easy, but you could run into incompatibility issues when you overwrite plugins already present - in your installation because of other features that you did install. Though they have the same name - it could happen that the versions of these colliding plugins are not equal, hence the possible - incompatibilities. The installation instructions are repeated in the 'readme.html' file. - </para> - </listitem> - </itemizedlist> - </section> + <section id="downloadingandinstallingjbpm"> + <title>Downloading and installing jBPM</title> + <para>To get the latest release jBPM 3 version, go to + the <ulink url="http://sourceforge.net/project/showfiles.php?group_id=70542&... jPDL 3 + package on Sourceforge.net</ulink> and download the latest installer. + </para> + <para id="jbpm-jpdl-{version}-installer.jar"><emphasis role="bold">The jPDL installer</emphasis> + creates a runtime installation and it can also download and install the + eclipse designer and a jboss server. You can use jBPM also without application server, but all of + these components are preconfigured to interoperate out-of-the-box to get you started with jBPM quickly. + To launch the installer, open a command line and go to the directory where you downloaded it. + Then type: + </para> + <programlisting>java -jar jbpm-jpdl-{version}-installer.jar</programlisting> + <para> + Step through the instructions. Any supported version of JBoss and the exact version + of eclipse can optionally be downloaded by the installer. + </para> + <para>When installing jBPM into JBoss, this will create a jBPM directory into a server + configuration's deploy directory. All jBPM files are centralized inside this <literal>deploy/jbpm</literal> + directory. No other files of your JBoss installation will be touched. + </para> + <para>If you don't want to install jBPM in JBoss, then you'll have to point the installer to an empty + temporary directory where it can put those files anyway. This limitation <ulink url="https://jira.jboss.org/jira/browse/JBPM-1814">will be removed + in the next version [JBPM-1814]</ulink>. + </para> + <para>You can use your own eclipse (if it is version 3.4+) or + you can use the eclipse that the installer downloaded. To install the graphical process designer in + eclipse, just use the eclipse update mechanism (Help --> Software Updates --> ...) and point it to the + file <literal>designer/jbpm-jpdl-designer-site.zip</literal>.</para> </section> <section> - <title>The JBoss jBPM project directory</title> - <itemizedlist> - <listitem><emphasis role="bold"><ulink url="mailto:sales@jboss.com?subject=jBPM professional support">professional support</ulink></emphasis>: JBoss is the company that backs this project with professional support, training and consultancy services.</listitem> - <listitem><emphasis role="bold">user guide</emphasis>: is the document you're reading and serves as the main entry point into the project.</listitem> - <listitem><emphasis role="bold"><ulink url="http://sourceforge.net/forum/?group_id=70542">forums<...;: get in contact with the community, ask questions and discuss jBPM</listitem> - <listitem><emphasis role="bold"><ulink url="http://www.jboss.org/wiki/Wiki.jsp?page=JbpmWiki">wiki&...;: extra information, mostly provided by the community</listitem> - <listitem><emphasis role="bold"><ulink url="http://jira.jboss.com/jira/secure/BrowseProject.jspa?id=10052&q... tracker</ulink></emphasis>: for submitting bugs and feature requests</listitem> - <listitem><emphasis role="bold"><ulink url="http://sourceforge.net/project/showfiles.php?group_id=70542&quo...;: sourceforge download page for jBPM</listitem> - <listitem><emphasis role="bold"><ulink url="http://sourceforge.net/mail/?group_id=70542">mailing lists</ulink></emphasis>: mailing lists are used for announcements</listitem> - <listitem><emphasis role="bold">javadocs</emphasis>: part of the download in the doc/javadoc directory.</listitem> - </itemizedlist> + <title>The JBoss jBPM cummunity page</title> + <para><ulink url="http://www.jboss.org/jbossjbpm/jbpm_community/">The jBPM Community Page</ulink> provides + all the details about where to find forums, wiki, issue tracker, + downloads, mailing lists and the source repositories. + </para> </section> - <section id="cvsaccess"> - <title>Source code CVS access</title> - - <section id="anonymouscvsaccess"> - <title>Anonymous CVS access</title> - <para>Alternatively, you can get JBoss jBPM from cvs with the following - information:</para> - <itemizedlist> - <listitem>Connection type: pserver</listitem> - <listitem>User: anonymous </listitem> - <listitem>Host: anoncvs.forge.jboss.com</listitem> - <listitem>Port: 2401 (which is the default)</listitem> - <listitem>Repository path: /cvsroot/jbpm</listitem> - <listitem>Label: :pserver:anonymous@anoncvs.forge.jboss.com:/cvsroot/jbpm</listitem> - </itemizedlist> - </section> - - <section id="developercvsaccess"> - <title>Developer CVS access</title> - <para>To get cvs developer access, you must sign contributors agreement and - you need an ssh key. More information on both can be found on - <ulink url="http://www.jboss.org/wiki/Wiki.jsp?page=CVSRepository">the JBoss cvs - repository wiki page</ulink></para> - <itemizedlist> - <listitem>Connection type: ext over ssh (extssh in eclipse)</listitem> - <listitem>User: sf.net username or jboss username </listitem> - <listitem>Host: cvs.forge.jboss.com</listitem> - <listitem>Port: 2401 (which is the default)</listitem> - <listitem>Repository path: /cvsroot/jbpm</listitem> - <listitem>Label: :pserver:anonymous@cvs.forge.jboss.com:/cvsroot/jbpm</listitem> - </itemizedlist> - </section> - </section> - </chapter> \ No newline at end of file Modified: jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/introduction.xml =================================================================== --- jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/introduction.xml 2008-11-09 12:00:11 UTC (rev 2828) +++ jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/introduction.xml 2008-11-09 12:01:09 UTC (rev 2829) @@ -95,10 +95,10 @@ environment like e.g. a webapplication, a swing application, an EJB, a webservice,... The jBPM library can also be packaged and exposed as a stateless session EJB. This allows clustered deployment and scalability for extreme high throughput. The stateless - session EJB will be written against the J2EE 1.3 specifications so that it is + session EJB will be written against the J2EE 1.4 specifications so that it is deployable on any application server. </para> - <para>Depending on the functionalities that you use, the library <literal>jbpm-jpdl.jar</literal> + <para>Depending on the functionalities that you use, the library <literal>lib/jbpm-jpdl.jar</literal> has some dependencies on other third party libraries such as e.g. hibernate, dom4j and others. We have done great efforts to require only those dependent libraries that you actually use. The dependencies are further documented in <xref linkend="deployment" /></para> Modified: jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/tutorial.xml =================================================================== --- jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/tutorial.xml 2008-11-09 12:00:11 UTC (rev 2828) +++ jbpm3/trunk/modules/userguide/src/main/docbook/en/modules/tutorial.xml 2008-11-09 12:01:09 UTC (rev 2829) @@ -13,15 +13,8 @@ <para>The best way to learn is to create a project and experiment by creating variations on the examples given.</para> - <para>To get started for eclipse users: download jbpm-3.0-[version].zip - and unzip it to your sytem. Then do &quot;File&quot; --> - &quot;Import...&quot; --> "Existing Project into Workspace". - Click &quot;Next&quot; Then, browse for the jBPM root directory - and click &quot;Finish&quot;. Now you have a jbpm.3 project in - your workspace. You can now find the examples of the tutorial - in <literal>src/java.examples/...</literal>. When you open these - examples, you can run them with &quot;Run&quot; --> - &quot;Run As...&quot; --> &quot;JUnit Test&quot;</para> + <para>To get started first, <link linkend="downloadingandinstallingjbpm"> + download and install</link> jBPM.</para> <para>jBPM includes a graphical designer tool for authoring the XML that is shown in the examples. You can find download instructions @@ -29,9 +22,6 @@ You don't need the graphical designer tool to complete this tutorial. </para> - <para>State machines can be - </para> - <section id="helloworldexample"> <title>Hello World example</title>