Author: mcaspers Date: 2011-01-19 23:31:18 -0500 (Wed, 19 Jan 2011) New Revision: 28424 Modified: trunk/drools/docs/guvnor_ref/en-US/functionality_overview.xml Log: General Updates Modified: trunk/drools/docs/guvnor_ref/en-US/functionality_overview.xml =================================================================== --- trunk/drools/docs/guvnor_ref/en-US/functionality_overview.xml 2011-01-20 04:19:02 UTC (rev 28423) +++ trunk/drools/docs/guvnor_ref/en-US/functionality_overview.xml 2011-01-20 04:31:18 UTC (rev 28424) @@ -1,349 +1,299 @@ <?xml version='1.0' encoding='UTF-8'?> <chapter id="functionality_overview"> - <?dbhtml filename="functionality_overview.html"?> - <chapterinfo> - <keywordset> - <keyword>JBoss Tools</keyword> - <keyword>Eclipse Guvnor Tools</keyword> - </keywordset> - </chapterinfo> + <?dbhtml filename="functionality_overview.html"?> + <chapterinfo> + <keywordset> + <keyword>JBoss Tools</keyword> + <keyword>Eclipse Guvnor Tools</keyword> + </keywordset> + </chapterinfo> - <title>Tasks</title> + <title>Tasks</title> - <para>This chapter will give an overview on all functionality the <property>Guvnor Tools</property> provides.</para> - - <section > - <title>Creating a New Guvnor Connection</title> - <para>As mentioned in the <xref linkend="introduction"/>, the main purpose - of the <property>EGT</property> is to allow development using resources held in a Guvnor - repository. The first task is to make a connection to a Guvnor repository. - This is handled by the <xref linkend="connection_wizard"/>. </para> - </section> - - <section id="local_copies"> - <title>Getting Local Copies of Guvnor Files</title> - <para>There are two methods of getting local copies of Guvnor repository - resources:</para> + <para>This chapter will give an overview on all functionality the <property>Guvnor Tools</property> provides.</para> - <orderedlist> - <listitem> - <para>Drag-and-drop from the <xref linkend="guvnor_repositories_view"/></para> - </listitem> - <listitem> - <para>Using the <xref linkend="resources_from_guvnor"/>, as described further in this document</para> - </listitem> - </orderedlist> + <section> + <title>Creating a New Guvnor Connection</title> + <para> + As mentioned in the <xref linkend="introduction"/> section, the main purposeof the <property>EGT</property> is to allow development using resources held in a Guvnor repository. The first task is to make a connection to a Guvnor repository. This is handled by the <guilabel>Connection Wizard</guilabel> (see <xref linkend="connection_wizard"/>). + </para> + </section> - <para>When local copies of Guvnor repository files are created, the <property>EGT</property> - sets an association between the local copy and the master file in the repository. This - information is kept in the (normally) hidden <emphasis> - <property>.guvnorinfo</property> - </emphasis> folder in the local project and, like all metadata, should not be changed by - end users.</para> + <section id="local_copies"> + <title>Getting Local Copies of Guvnor Files</title> + <para>There are two methods of getting local copies of Guvnor repository resources:</para> - <figure> - <title>.guvnorinfo metadata</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/functionality_overview/guvnorinfo.png"/> - </imageobject> - </mediaobject> - </figure> + <orderedlist> + <listitem> + <para>Drag-and-drop from the Guvnor Repositories View, as described in the <xref linkend="guvnor_repositories_view"/> section</para> + </listitem> + <listitem> + <para>Using the Resource from Guvnor Wizard, as described in the <xref linkend="resources_from_guvnor"/> section</para> + </listitem> + </orderedlist> - <para>The association allows for operations such as update and commit in - synchronization with the master copy held in the Guvnor repository.</para> + <para> + When local copies of Guvnor repository files are created, the <property>EGT</property> sets an association between the local copy and the master file in the repository. This information is kept in the (normally) hidden <filename>.guvnorinfo</filename> folder in the local project and, like all metadata, should not be changed by end users. + </para> + + <figure> + <title>.guvnorinfo metadata</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/functionality_overview/guvnorinfo.png"/> + </imageobject> + </mediaobject> + </figure> + + <para> + The association allows for operations such as update and commit in synchronization with the master copy held in the Guvnor repository. + </para> - <para>The <property>EGT</property> decorates local resources associated with Guvnor - repository master copies. This decoration appears in Eclipse views conforming to the - Eclipse Common Navigator framework, such as the Eclipse <property>Resource - Navigator</property> and the Java <property>Package Explorer</property>. On the image - above you can see the <emphasis> - <property>Dummy rule.drl</property></emphasis> file with the decoration in the <property>Resource Navigator</property>. The Guvnor icon decorator is on the top right of the file image, and the Guvnor - revision details are appended to the file name. (The presence/location of these can be - changed in the <xref linkend="resource_decoration_preferences"/>.)</para> + <para> + The <property>EGT</property> decorates local resources associated with Guvnor repository master copies. This decoration appears in Eclipse views conforming to the Eclipse Common Navigator framework, such as the Eclipse <guilabel>Resource Navigator</guilabel> and the Java <guilabel>Package Explorer</guilabel>. In the image above you can see the <filename>Dummy rule.drl</filename> file with the decoration in the <guilabel>Resource Navigator</guilabel>. The Guvnor icon decorator is on the top right of the file image, and the Guvnor revision details are appended to the file name. The presence/location of these can be changed in the <guilabel>Local Guvnor Repository Resource Decoration Preferences</guilabel> (see the <xref linkend="resource_decoration_preferences"/> section). + </para> - <para>Here we see that, <emphasis><property>Dummy rule.drl</property></emphasis> is associated with a Guvnor repository - resource and the local copy is based on revision 0, with a <code>02-10-2008, 4:21:53</code> date/time - stamp. The file <emphasis><property>Sample.drl</property>,</emphasis> however, is not associated with a Guvnor repository - file. Further details about the association can be found in the standard Eclipse - properties page, accessed via the <emphasis><property>Properties</property></emphasis> option in the context menu:</para> + <para> + Here we see that the <filename>Dummy rule.drl</filename> file is associated with a Guvnor repository resource and the local copy is based on revision 0, with a <code>02-10-2008, 4:21:53</code> date/time stamp. However, the file <filename>Sample.drl</filename> is not associated with a Guvnor repository file. Further details about the association can be found in the standard Eclipse properties page, accessed via the <guilabel>Properties</guilabel> option in the context menu: + </para> + + <figure> + <title>Association Details</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/functionality_overview/association_details.png"/> + </imageobject> + </mediaobject> + </figure> - <figure> - <title>Association Details</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/functionality_overview/association_details.png"/> - </imageobject> - </mediaobject> - </figure> + <para> + The <property>EGT</property> adds a property page to the standard Eclipse properties dialog, the contents of which are shown above. It displays the specific Guvnor repository, the location within the repository, the version (date/time stamp) and the revision number. + </para> + </section> - <para>The <property>EGT</property> contributes a property page to the standard Eclipse - properties dialog, the contents of which are shown above. It displays the specific Guvnor - repository, the location within the repository, the version (date/time stamp) and - the revision number.</para> - </section> - - <section id="actions"> - <title>Managing Guvnor Resources</title> + <section id="actions"> + <title>Managing Guvnor Resources</title> - <para>The <property>EGT</property> provides a number of actions (available through the - <emphasis><property>Guvnor</property></emphasis> context menu on files) for working with files, both those associated with - Guvnor repository master copies and those not associated. The actions are:</para> + <para> + The <property>EGT</property> provides a number of actions (available through the <guilabel>Guvnor</guilabel> context menu on files) for working with files, both those associated with Guvnor repository master copies and those not associated. The actions are: + </para> - <itemizedlist> - <listitem> - <para> - <xref linkend="update_action"/> - </para> - </listitem> - <listitem> - <para> - <xref linkend="add_action"/> - </para> - </listitem> - <listitem> - <para> - <xref linkend="commit_action"/> - </para> - </listitem> - <listitem> - <para> - <xref linkend="show_history_action"/> - </para> - </listitem> - <listitem> - <para> - <xref linkend="compare_with_version"/> - </para> - </listitem> - <listitem> - <para> - <xref linkend="switch_to_version"/> - </para> - </listitem> - <listitem> - <para> - <xref linkend="delete_action"/> - </para> - </listitem> - <listitem> - <para> - <xref linkend="disconnect_action"/> - </para> - </listitem> - </itemizedlist> + <itemizedlist> + <listitem> + <para> + <xref linkend="update_action"/> + </para> + </listitem> + <listitem> + <para> + <xref linkend="add_action"/> + </para> + </listitem> + <listitem> + <para> + <xref linkend="commit_action"/> + </para> + </listitem> + <listitem> + <para> + <xref linkend="show_history_action"/> + </para> + </listitem> + <listitem> + <para> + <xref linkend="compare_with_version"/> + </para> + </listitem> + <listitem> + <para> + <xref linkend="switch_to_version"/> + </para> + </listitem> + <listitem> + <para> + <xref linkend="delete_action"/> + </para> + </listitem> + <listitem> + <para> + <xref linkend="disconnect_action"/> + </para> + </listitem> + </itemizedlist> - <para>Each of these actions is described below.</para> + <para>Each of these actions is described below.</para> - <section id="update_action"> - <title>Update Action</title> + <section id="update_action"> + <title>Update Action</title> - <para>The <emphasis> - <property>Update</property> - </emphasis> action is available for one or more Guvnor resources that are not in - synchronization with the Guvnor repository master copies. These resources would not - be in synchronization because either/both</para> + <para> + The <guilabel>Update</guilabel> action is available for one or more Guvnor resources that are not in synchronization with the Guvnor repository master copies. These resources would not be in synchronization due to one or or both of the following conditions: + </para> + + <orderedlist> + <listitem> + <para>There are local changes to these resources</para> + </listitem> + <listitem> + <para>The master copies have been changed in the Guvnor repository</para> + </listitem> + </orderedlist> - <orderedlist> - <listitem><para>There are local changes to these - resources</para></listitem> - <listitem><para>The master copies have been changed in the Guvnor repository</para></listitem> - </orderedlist> + <para> + Performing the <guilabel>Update</guilabel> action replaces the local file contents with the current contents from the Guvnor repository master copies (equivalent to <xref linkend="switch_to_version"/> for the latest version). + </para> + </section> - <para>Performing the <emphasis> - <property>Update</property> - </emphasis> action replaces the local file contents with the current contents from - the Guvnor repository master copies (equivalent to <emphasis> - <xref linkend="switch_to_version"/> - </emphasis> for the latest version).</para> - </section> + <section id="add_action"> + <title>Add Action</title> - <section id="add_action"> - <title>Add Action</title> + <para>The <guilabel>Add</guilabel> action is available for one or more local files that are not associated with a Guvnor repository master copy. Choosing the <guilabel>Add</guilabel> action launches the <guilabel>Add to Guvnor wizard</guilabel>:</para> + + <figure> + <title>Add to Guvnor Wizard</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/functionality_overview/add_toGuvnor_wizard.png"/> + </imageobject> + </mediaobject> + </figure> - <para>The <emphasis> - <property>Add</property> - </emphasis> action is available for one or more local files that are not associated - with a Guvnor repository master copy. Choosing the <emphasis> - <property>Add</property> - </emphasis> action launches the <property>Add to Guvnor wizard</property>:</para> + <para> + The first page of the wizard asks for the selection of the target Guvnor repository and gives the choice to create a new Guvnor repository connection (in which case the second page is the same as the <xref linkend="guvnor_connection_wizard"/>). Once the target Guvnor repository is chosen, the wizard then asks for the folder location to add the selection files: + </para> + + <figure> + <title>Selecting a Target Folder</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/functionality_overview/select_target_folder.png"/> + </imageobject> + </mediaobject> + </figure> - <figure> - <title>Add to Guvnor Wizard</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/functionality_overview/add_toGuvnor_wizard.png"/> - </imageobject> - </mediaobject> - </figure> + <para>Here the <filename>&quot;defaultPackage&quot;</filename> folder is selected as the destination location.</para> - <para>The first page of the wizard asks for the selection of the target Guvnor - repository and gives the choice to create a new Guvnor repository connection (in - which case the second page is the same as the <xref linkend="guvnor_connection_wizard"/>). Once the target Guvnor repository is chosen, - the wizard then asks for the folder location to add the selection files:</para> + <note> + <title>Note:</title> + <para> + Note that the <filename>&quot;snapshot&quot;</filename> folder in the Guvnor repository is read-only for <property>EGT</property>, and hence not visible as a candidate location in this wizard. The Guvnor repository web administration tools must be used to add snapshot content. + </para> + </note> - <figure> - <title>Selecting a Target Folder</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/functionality_overview/select_target_folder.png"/> - </imageobject> - </mediaobject> - </figure> + <para> + Clicking on the <guibutton>Finish</guibutton> adds the selected files to the Guvnor repository and creates an association between the local and Guvnor repository files. + </para> - <para>Here the <emphasis> - <property>&quot;defaultPackage&quot;</property></emphasis> folder is selected as the destination - location.</para> + <note> + <title>Note:</title> + <para>Note that the wizard will not allow for overwrite of existing Guvnor repository files. Another target location must be chosen.</para> + </note> + </section> - <note> - <title>Note:</title> - <para>Note that the <emphasis> - <property>&quot;snapshot&quot;</property></emphasis> folder in the Guvnor repository is read-only for - <property>EGT</property>, and hence not visible as a candidate location in - this wizard. The Guvnor repository web administration tools must be used to add - snapshot content.</para> - </note> + <section id="commit_action"> + <title>Commit Action</title> - <para>Clicking on <emphasis> - <property>Finish</property> - </emphasis> adds the selected files to the Guvnor repository and creates an - association between the local and Guvnor repository files.</para> + <para> + The <guilabel>Commit</guilabel> action is enabled for one or more Guvnor repository associated files that have local changes. The <guilabel>Commit</guilabel> action will write the local changes back to the associated Guvnor repository files and update the association for the new revision created. + </para> - <note> - <title>Note:</title> - <para>Note that the wizard will not allow for overwrite of existing Guvnor - repository files. Another target location must be chosen.</para> - </note> - </section> + <para> + If a local change is based on an older revision of a file that is currently in the Guvnor repository (for example, someone else changed the same file), then the <guilabel>Commit</guilabel> action will ask whether you wish to overwrite the current version in the Guvnor repository with the local content. When such conflicts occur, however, you should use the Eclipse Guvnor version tools, along with Eclipse standard tools, to determine the differences and merge content based on the current version in the Guvnor repository. + </para> + </section> - <section id="commit_action"> - <title>Commit Action</title> + <section id="show_history_action"> + <title>Show History Action</title> - <para>The <emphasis> - <property>Commit</property> - </emphasis> action is enabled for one or more Guvnor repository associated files - that have local changes. The <emphasis> - <property>Commit</property> - </emphasis> action will write the local changes back to the associated Guvnor - repository files and update the association for the new revision created.</para> + <para> + The <guilabel>Show History</guilabel> action is enabled for one Guvnor repository associated file and causes the <xref linkend="guvnor_history_view"/> to be populated with revision history for the selected file. + </para> + </section> - <para>If a local change is based on an older revision of a file that is currently in the - Guvnor repository (for example, someone else changed the same file), then the <emphasis> - <property>Commit</property> - </emphasis> action will ask whether you wish to overwrite the current version in the - Guvnor repository with the local content. When such conflicts occur, however, you - should use the Eclipse Guvnor version tools, along with Eclipse standard tools, to - determine the differences and merge content based on the current version in the - Guvnor repository.</para> - </section> + <section id="compare_with_version"> + <title>Compare with Version Action</title> - <section id="show_history_action"> - <title>Show History Action</title> + <para> + The <guilabel>Compare with Version</guilabel> action is enabled for one Guvnor repository associated file. This action first opens a wizard asking for the version for comparison (with the local file contents): + </para> + + <figure> + <title>Compare with Version Wizard</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/functionality_overview/compare_with_version.png"/> + </imageobject> + </mediaobject> + </figure> - <para>The <emphasis> - <property>Show History</property> - </emphasis> action is enabled for one Guvnor repository associated file and causes - the <xref linkend="guvnor_history_view"/> to be - populated with revision history for the selected file.</para> - </section> + <para>Once the revision is selected, the action opens the Eclipse <guilabel>Compare editor</guilabel> (read-only):</para> + <figure> + <title>Eclipse Compare Editor</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/functionality_overview/compare_with_version2.png"/> + </imageobject> + </mediaobject> + </figure> - <section id="compare_with_version"> - <title>Compare with Version Action</title> + <guilabel> + This editor uses Eclipse-standard comparison techniques to show the differences in the two versions. In cases where there are no differences, the editor will not open, rather a dialog saying that there are no differences will appear. + </guilabel> + <figure> + <title>Alert Dialog</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/functionality_overview/compare_with_version3.png"/> + </imageobject> + </mediaobject> + </figure> + </section> - <para>The <emphasis> - <property>Compare with Version</property> - </emphasis> action is enabled for one Guvnor repository associated file. This action - first opens a wizard asking for the version for comparison (with the local file - contents):</para> + <section id="switch_to_version"> + <title>Switch to Version Action</title> - <figure> - <title>Compare with Version Wizard</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/functionality_overview/compare_with_version.png"/> - </imageobject> - </mediaobject> - </figure> + <para>The <guilabel>Switch to Version</guilabel> action is enabled for one Guvnor repository associated file.</para> + <para>First the <guilabel>Switch to Version</guilabel> action prompts for selection of version:</para> + + <figure> + <title>Select Version Window</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/functionality_overview/compare_with_version.png"/> + </imageobject> + </mediaobject> + </figure> - <para>Once the revision is selected, the action opens the Eclipse <property>Compare - editor</property> (read-only):</para> - <figure> - <title>Eclipse Compare Editor</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/functionality_overview/compare_with_version2.png"/> - </imageobject> - </mediaobject> - </figure> + <para> + Once the version is selected, the <guilabel>Switch to Version</guilabel> action replaces the local file contents with those from the revision selected. + </para> + </section> - <para>This editor uses Eclipse-standard comparison techniques to show the differences in - the two versions. In cases where there are no differences, the editor will not open, - rather a dialog saying that there are no differences will appear.</para> - <figure> - <title>Alert Dialog</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/functionality_overview/compare_with_version3.png"/> - </imageobject> - </mediaobject> - </figure> - </section> + <section id="delete_action"> + <title>Delete Action</title> - <section id="switch_to_version"> - <title>Switch to Version Action</title> + <para> + The <guilabel>Delete</guilabel> action is enabled for one or more Guvnor repository associated files. After confirmation via a dialog, the <guilabel>Delete</guilabel> action removes the files in the Guvnor repository and deletes local metadata for the Guvnor repository association. + </para> + + <figure> + <title>Comfirm Delete Dialog</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/functionality_overview/confirm_delete.png"/> + </imageobject> + </mediaobject> + </figure> + </section> - <para>The <emphasis> - <property>Switch to Version</property> - </emphasis> action is enabled for one Guvnor repository associated file.</para> - <para>First the <emphasis> - <property>Switch to Version</property> - </emphasis> action prompts for selection of version:</para> + <section id="disconnect_action"> + <title>Disconnect Action</title> - <figure> - <title>Select Version Window</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/functionality_overview/compare_with_version.png"/> - </imageobject> - </mediaobject> - </figure> - - <para>Once the version is selected, the <emphasis> - <property>Switch to Version</property> - </emphasis> action replaces the local file contents with those from the revision - selected.</para> - </section> - - <section id="delete_action"> - <title>Delete Action</title> - - <para>The <emphasis> - <property>Delete</property> - </emphasis> action is enabled for one or more Guvnor repository associated files. - After confirmation via a dialog, the <emphasis> - <property>Delete</property> - </emphasis> action removes the files in the Guvnor repository and deletes local - metadata for the Guvnor repository association.</para> - - <figure> - <title>Comfirm Delete Dialog</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/functionality_overview/confirm_delete.png"/> - </imageobject> - </mediaobject> - </figure> - </section> - - <section id="disconnect_action"> - <title>Disconnect Action</title> - - <para>The <emphasis> - <property>Disconnect</property> - </emphasis> action is enabled for one or more Guvnor repository associated files, - and removes local metadata for the Guvnor repository association.</para> - </section> - </section> + <para> + The <guilabel>Disconnect</guilabel> action is enabled for one or more Guvnor repository associated files, and removes local metadata for the Guvnor repository association. + </para> + </section> + </section> - + </chapter>