December 2008 - jbosstools-commits

JBoss Tools SVN: r12780 - in branches/jbosstools-3.0.0.CR1/portlet/docs/reference/en: modules and 1 other directory.

by jbosstools-commits＠lists.jboss.org

Author: smukhina Date: 2008-12-19 14:55:55 -0500 (Fri, 19 Dec 2008) New Revision: 12780 Added: branches/jbosstools-3.0.0.CR1/portlet/docs/reference/en/master_output.xml Modified: branches/jbosstools-3.0.0.CR1/portlet/docs/reference/en/master.xml branches/jbosstools-3.0.0.CR1/portlet/docs/reference/en/modules/jsf_portlet.xml branches/jbosstools-3.0.0.CR1/portlet/docs/reference/en/modules/portlets_to_nonWTP_projects.xml branches/jbosstools-3.0.0.CR1/portlet/docs/reference/en/modules/seam_portlet.xml branches/jbosstools-3.0.0.CR1/portlet/docs/reference/en/modules/starting_project.xml Log: https://jira.jboss.org/jira/browse/JBDS-324 the latest docs that are done for release 3.0.0.CR1 from trunk are added to branch master_output - the file to build guide versions with highlighted diff markers Modified: branches/jbosstools-3.0.0.CR1/portlet/docs/reference/en/master.xml =================================================================== --- branches/jbosstools-3.0.0.CR1/portlet/docs/reference/en/master.xml 2008-12-19 19:49:50 UTC (rev 12779) +++ branches/jbosstools-3.0.0.CR1/portlet/docs/reference/en/master.xml 2008-12-19 19:55:55 UTC (rev 12780) @@ -38,7 +38,7 @@ <holder>JBoss, a division of Red Hat Inc.</holder> </copyright> <releaseinfo> - Version: 3.0.0.beta1 + Version: 3.0.0.CR1 </releaseinfo> <abstract> Added: branches/jbosstools-3.0.0.CR1/portlet/docs/reference/en/master_output.xml =================================================================== --- branches/jbosstools-3.0.0.CR1/portlet/docs/reference/en/master_output.xml (rev 0) +++ branches/jbosstools-3.0.0.CR1/portlet/docs/reference/en/master_output.xml 2008-12-19 19:55:55 UTC (rev 12780) @@ -0,0 +1,874 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" +"http://www.docbook.org/xml/4.3/docbookx.dtd" + +[<!ENTITY intro SYSTEM "modules/intro.xml"> +<!ENTITY installation SYSTEM "modules/installation.xml"> +<!ENTITY starting_project SYSTEM "modules/starting_project.xml"> +<!ENTITY jsf_portlet SYSTEM "modules/jsf_portlet.xml"> +<!ENTITY seam_portlet SYSTEM "modules/seam_portlet.xml"> +<!ENTITY portlets_to_nonWTP_projects SYSTEM "modules/portlets_to_nonWTP_projects.xml"> + +<!ENTITY seamlink "../../seam/html_single/index.html"> +<!ENTITY aslink "../../as/html_single/index.html"> +<!ENTITY esblink "../../esb_ref_guide/html_single/index.html"> +<!ENTITY gsglink "../../GettingStartedGuide/html_single/index.html"> +<!ENTITY hibernatelink "../../hibernatetools/html_single/index.html"> +<!ENTITY jbpmlink "../../jbpm/html_single/index.html"> +<!ENTITY jsflink "../../jsf/html_single/index.html"> +<!ENTITY jsfreflink "../../jsf_tools_ref_guide/html_single/index.html"> +<!ENTITY jsftutoriallink "../../jsf_tools_tutorial/html_single/index.html"> +<!ENTITY strutsreflink "../../struts_tools_ref_guide/html_single/index.html"> +<!ENTITY strutstutoriallink "../../struts_tools_tutorial/html_single/index.html"> +]><book xmlns:diffmk="http://diffmk.sf.net/ns/diff"> + + <bookinfo> + <title>JBoss Portal Tools Reference Guide</title> + + <author><firstname>Olga</firstname><surname>Chikvina</surname></author> + <author><firstname>Snjezana</firstname><surname>Peco</surname><email>snjezana.peco(a)redhat.com</email></author> + <author><firstname>Svetlana</firstname><surname>Mukhina</surname><email>smukhina(a)exadel.com</email></author> + <author><firstname>Thomas</firstname><surname>Heute</surname><email>theute(a)jboss.org</email></author> + + <pubdate>September 2008</pubdate> + <copyright> + <year>2008</year> + <holder>JBoss, a division of Red Hat Inc.</holder> + </copyright> + <releaseinfo><diffmk:wrapper diffmk:change="changed"> + Version: 3.0.0.CR1 + </diffmk:wrapper></releaseinfo> + +<abstract diffmk:change="added"> + <title diffmk:change="added"></title> + <para diffmk:change="added"> + <ulink diffmk:change="added" url="http://download.jboss.org/jbosstools/nightly-docs/en/jboss_portal_tools_r..."><diffmk:wrapper diffmk:change="added">PDF version</diffmk:wrapper></ulink> + </para> +</abstract> + + + </bookinfo> + <toc></toc> + + + +<chapter id="intro" xml:base="file:///home/ochikvina/WORK/for_compare/trunk/portlet/docs/reference/en/modules/intro.xml" xreflabel="intro"> + <?dbhtml filename="intro.html"?> + <title>Introduction</title> + + <para>Starting from 3.0.0.Alpha1 version, JBoss set of plugins extends <property moreinfo="none">JBoss Portal</property> + features. Thus, this guide is intended to explain you how to manage the functionality + <property moreinfo="none">JBoss Tools</property> provide to ease the development with <property moreinfo="none">JBoss + Portal</property>.</para> + + <section id="preface"> + <title>Preface</title> + <para><property moreinfo="none">JBoss Portal</property> provides an open source platform for hosting and + serving a portal's Web interface, publishing and managing its content, and customizing + its experience. It supports a wide range of features, including standard portlets, + single sign-on, clustering, and internationalization.</para> + </section> + + <section id="key_features"> + <title>Key Features</title> + <para>The next table lists key features supplied by <property moreinfo="none">JBoss Portal Tools</property>.</para> + + <table> + <title>Key Functionality of JBoss Portal Tools</title> + <tgroup cols="3"> + + <colspec align="left" colnum="1" colwidth="1*"></colspec> + <colspec colnum="2" colwidth="5*"></colspec> + <colspec align="left" colnum="3" colwidth="1*"></colspec> + + <thead> + <row> + <entry>Feature</entry> + <entry>Benefit</entry> + <entry>Chapter</entry> + </row> + </thead> + + <tbody> + + <row> + <entry> + <para>Wizards for creating Projects with Portlet Facets</para> + </entry> + <entry> + <para>New Dynamic Web Project wizard allows you to select a proper + Configuration to enable Portlet Facet in it.</para> + </entry> + <entry> + <link linkend="creating_project_with_jbossportal">Creating a Dynamic + Web Project</link> + </entry> + </row> + + + <row> + <entry> + <para>Create Java Portlet wizard</para> + </entry> + + <entry> + <para>The wizard enables creating a JSR-186/JSR-286 compliant + portlet.</para> + </entry> + <entry> + <link linkend="adding_java_portlet">Adding Java Portlet to a + project</link> + </entry> + </row> + + <row> + <entry> + <para>Create JSF/Seam Portlet wizard</para> + </entry> + <entry> + <para><diffmk:wrapper diffmk:change="changed">This wizard allows to create JSF/Seam portlets</diffmk:wrapper></para> + </entry> + <entry> + <link diffmk:change="added" linkend="jsf_portlet"><diffmk:wrapper diffmk:change="added">Creating JSF Portlet</diffmk:wrapper></link> + <link diffmk:change="added" linkend="seam_portlet"><diffmk:wrapper diffmk:change="added">Creating Seam Portlet</diffmk:wrapper></link> + </entry> + </row> + + </tbody> + </tgroup> + </table> + </section> + + <section id="rel_resources"> + <title>Other relevant resources on the topic</title> + + <itemizedlist> + <listitem> + <para> + <ulink url="http://www.jboss.org/jbossportal/">JBoss Portal Home Page</ulink> + </para> + </listitem> + + <listitem> + <para> + <ulink url="http://wiki.jboss.org/wiki/JBossPortal">JBoss Portal Wiki</ulink> + </para> + </listitem> + + <listitem> + <para> + <ulink url="http://www.jboss.org/tools/">JBoss Tools Home Page</ulink> + </para> + </listitem> + + <listitem> + <para> + <ulink url="http://www.jboss.com/index.html?module=bb&op=viewforum&f=201">JBoss Tools Forum</ulink> + </para> + </listitem> + + <listitem> + <para> + <ulink url="http://download.jboss.org/jbosstools/nightly-docs/">The latest + JBossTools/JBDS documentation builds</ulink> + </para> + </listitem> + + <listitem> + <para> + <ulink url="http://www.jboss.com/products/devstudio/docs">Stable JBossTools/JBDS + documentation</ulink> (supplied with the latest JBDS release, 1.1.0 GA + currently) </para> + </listitem> + </itemizedlist> + + </section> +</chapter> + + +<chapter id="installation" xml:base="file:///home/ochikvina/WORK/for_compare/trunk/portlet/docs/reference/en/modules/installation.xml" xreflabel="installation"> + <?dbhtml filename="installation.html"?> + <title>Installation issues</title> + + <para>This section provides you with the steps on how to start with <property moreinfo="none">JBoss + Portal</property> and integrated features using <property moreinfo="none">JBoss Tools</property>.</para> + + <itemizedlist> + <listitem> + <para>First, you need to have Eclipse Ganymede with JBoss Tools 3.0.0.Alpha1 and higher installed.</para> + + <tip> + <title>Tip:</title> + <para>Read <ulink url="../../GettingStartedGuide/html_single/index.html#JBossToolsInstall">JBoss Tools + Installation</ulink> section in our Getting Started documentation to find out + how to install <property moreinfo="none">JBoss Tools</property> onto Eclipse.</para> + </tip> + </listitem> + + <listitem> + <para>Next, download the JBoss Portal + JBoss AS bundle from <ulink url="http://www.jboss.org/jbossportal/download/index.html">JBoss Portal Download + page</ulink></para> + + <note> + <title>Note:</title> + <para>You need JBoss Portal 2.7 if you want to work with a Portlet 2.0</para> + </note> + + </listitem> + + <listitem> + <para>Extract the bundle wherever you want on your hard drive</para> + </listitem> + </itemizedlist> + + <para>Now, when you have it installed, we are going to demonstrate some powerful features of + <property moreinfo="none">JBoss Portal</property> tooling for Eclipse.</para> +</chapter> + + +<chapter id="starting_project" xml:base="file:///home/ochikvina/WORK/for_compare/trunk/portlet/docs/reference/en/modules/starting_project.xml" xreflabel="starting_project"> + <?dbhtml filename="starting_project.html"?> + <title>Starting the Project with JBoss Portal</title> + + <para>To get started with <property moreinfo="none">JBoss Portal</property> and <property moreinfo="none">JBoss + Tools</property><diffmk:wrapper diffmk:change="added">, you should first have a Web Project pointed to the JBoss Portal Runtime. + Thus, in this chapter we are going to show you how to create a Dynamic Web Project, add Java + Portlet to it and deploy it to the </diffmk:wrapper><property diffmk:change="added" moreinfo="none"><diffmk:wrapper diffmk:change="added">JBoss Portal</diffmk:wrapper></property><diffmk:wrapper diffmk:change="added">.</diffmk:wrapper></para> + + <section id="creating_project_with_jbossportal"> + <title>Creating a Dynamic Web Project</title> + + <para>To create a Dynamic Web Project, go to <emphasis> + <property moreinfo="none">File > New > Dynamic Web Project</property> + </emphasis> if you are in the <property moreinfo="none">Web Perspective</property> or <property moreinfo="none">File > + New > Other > Web > Dynamic Web Project</property> in any other Perspective. The + first page of the New Dynamic Web Project wizard looks as follows.</para> + + <figure float="0"> + <title>New Dynamic Web Project</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/starting_project/starting_project_1.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para><diffmk:wrapper diffmk:change="changed">Fill out the name of your project. Next, click the </diffmk:wrapper><emphasis> + <property moreinfo="none"><diffmk:wrapper diffmk:change="changed">New</diffmk:wrapper></property> + </emphasis> button in the <emphasis> + <property moreinfo="none">Target Runtime</property> + </emphasis> section to specify a new Target Runtime. Click <emphasis> + <property diffmk:change="added" moreinfo="none"><diffmk:wrapper diffmk:change="added">JBoss 4.2 Runtime</diffmk:wrapper></property> + </emphasis> and press <emphasis> + <property moreinfo="none">Next</property>.</emphasis></para> + + <figure float="0"> + <title>New Server Runtime</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/starting_project/starting_project_2.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para><diffmk:wrapper diffmk:change="changed">On the next page you should give a name to the runtime. Let's call it </diffmk:wrapper><emphasis> + <property diffmk:change="added" moreinfo="none">JBoss Portal 2.7 Runtime</property> + </emphasis><diffmk:wrapper diffmk:change="changed">, and then point it to the location of your JBoss AS + Portal + installation.</diffmk:wrapper></para> + + <note> + <title>Note:</title> + + <para>The JBoss Tools Portlet feature has been tested using 2.6.5 and 2.7.0.ALPHA + versions of <property moreinfo="none">JBoss Portal</property>. Remember, if you want to use Portlet + version 2.0 (JSR-268), you have to choose JBoss Portal 2.7.</para> + </note> + + <figure float="0"> + <title>Target Runtime</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/starting_project/starting_project_3.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para><diffmk:wrapper diffmk:change="changed">Click </diffmk:wrapper><emphasis> + <property moreinfo="none">Finish</property>.</emphasis></para> + + <para diffmk:change="added"><diffmk:wrapper diffmk:change="added">On the next step you should click the </diffmk:wrapper><emphasis diffmk:change="added"> + <property moreinfo="none"><diffmk:wrapper diffmk:change="changed">Modify</diffmk:wrapper></property> + </emphasis><diffmk:wrapper diffmk:change="added"> button next to the </diffmk:wrapper><property moreinfo="none"><diffmk:wrapper diffmk:change="changed">Configuration</diffmk:wrapper></property><diffmk:wrapper diffmk:change="added"> section to enable + Portlet Facets for the project.</diffmk:wrapper></para> + +  + + <figure diffmk:change="added" float="0"> + <title diffmk:change="added"><diffmk:wrapper diffmk:change="added">Setting the Project Configuration</diffmk:wrapper></title> + <mediaobject diffmk:change="added"> + <imageobject diffmk:change="added"> + <imagedata diffmk:change="added" fileref="images/starting_project/starting_project_4.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para diffmk:change="added"><diffmk:wrapper diffmk:change="added">On this page you should check the </diffmk:wrapper><emphasis> + <property diffmk:change="added" moreinfo="none"><diffmk:wrapper diffmk:change="added">JBoss Core Portlet</diffmk:wrapper></property> + </emphasis><diffmk:wrapper diffmk:change="changed"> and press </diffmk:wrapper><emphasis> + <property diffmk:change="added" moreinfo="none"><diffmk:wrapper diffmk:change="added">OK</diffmk:wrapper></property> + </emphasis>.</para> + + <figure float="0"> + <title><diffmk:wrapper diffmk:change="changed">Enabling the Portlet Facet</diffmk:wrapper></title> + <mediaobject> + <imageobject> + <imagedata fileref="images/starting_project/starting_project_4_a.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>The last wizard page is for configuring web modules. Here all values are set, so you + can leave everything as it is.</para> + + <figure float="0"> + <title>The Project Web Modules</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/starting_project/starting_project_5.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>Press <emphasis> + <property moreinfo="none">Finish</property>.</emphasis> + </para> + + <para>That's it! Our base project is done.</para> + + </section> + + <section id="structure_overview"> + <title>The Project Structure Overview</title> + + <para>Now, let's look at the structure of the just created project.</para> + + <figure float="0"> + <title>The Project Structure Overview</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/starting_project/starting_project_6.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>Here <property moreinfo="none">JBoos Tools</property><diffmk:wrapper diffmk:change="changed"> added JBoss Portlet facet to the project, + created an empty </diffmk:wrapper><emphasis> + <property moreinfo="none">portlet.xml</property> + </emphasis><diffmk:wrapper diffmk:change="changed"> file and added the Portlet library to the project classpath.</diffmk:wrapper></para> + </section> + + <section id="adding_java_portlet"> + <title>Adding a Java Portlet to the Project</title> + + <para><diffmk:wrapper diffmk:change="changed">At this point we'll show what the steps you need to proceed to add a new Java + Portlet to the project.</diffmk:wrapper></para> + + <para><diffmk:wrapper diffmk:change="added">Call the </diffmk:wrapper><property diffmk:change="added" moreinfo="none"><diffmk:wrapper diffmk:change="added">Create Portlet wizard</diffmk:wrapper></property><diffmk:wrapper diffmk:change="added"> by selecting </diffmk:wrapper><emphasis> + <property moreinfo="none"><diffmk:wrapper diffmk:change="changed">New > Other > JBoss Tools Web > Portlet > Java + Portlet</diffmk:wrapper></property>.</emphasis></para> + + <figure float="0"> + <title>New Java Portlet</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/starting_project/starting_project_7.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para><diffmk:wrapper diffmk:change="changed">The wizard fills in the Web Project and Source Folder fields for you. Then you need to + specify the Java package and the Class name and click </diffmk:wrapper><emphasis> + <property moreinfo="none">Next</property> + </emphasis>.</para> + + <figure float="0"> + <title>Specifying Class File Destination</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/starting_project/starting_project_8.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>On the other page you will be able to set the display name of the Portlet, a title, a + description, the supported modes and init parameters.</para> + + <figure float="0"> + <title>Specifying Class File Destination</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/starting_project/starting_project_9.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para><diffmk:wrapper diffmk:change="changed">On the next screen you can define which methods from + </diffmk:wrapper><emphasis>GenericPortlet</emphasis> you want to override.</para> + + <figure float="0"> + <title>Specifying Class File Destination</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/starting_project/starting_project_10.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>The last screen lets you build <property moreinfo="none">JBoss Portal</property> specific descriptors + to create an instance during the deployment and place it directly on the Portal.</para> + + <figure float="0"> + <title>Specifying Class File Destination</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/starting_project/starting_project_11.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <tip> + <title>Tip:</title> + + <para>If you uncheck the <emphasis> Create Portlet Instance</emphasis> checkbox, + <property moreinfo="none">JBoss Tools</property> won't create the deployment elements + in the <emphasis> default-object.xml</emphasis> and <emphasis><diffmk:wrapper diffmk:change="changed"> + portlet-instances.xml</diffmk:wrapper></emphasis> files.</para> + </tip> + + <para>Once Java Portlet is created, new resources have been added to the project structure. + As you can see on the figure below, it adds a Java Portlet class (<emphasis> + <property moreinfo="none">TestPortlet.java</property> + </emphasis> in our case), <emphasis> + <property moreinfo="none">default-object.xml</property> + </emphasis> and <emphasis> + <property moreinfo="none">portlet-instances.xml</property> + </emphasis> files and updates <emphasis> + <property moreinfo="none">portlet.xml</property> + </emphasis> as well.</para> + + <figure float="0"> + <title>The structure of Web Project with Java Portlet created</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/starting_project/starting_project_12.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>Thus, now the Project is ready to be built and deployed.</para> + </section> + + <section id="deploying_to_portal"> + <title><diffmk:wrapper diffmk:change="changed">Deploying a Portlet to JBoss Portal</diffmk:wrapper></title> + + <para><diffmk:wrapper diffmk:change="added">You can deploy the created project in the way you deploy any other Web Application. + Right click on the project and do </diffmk:wrapper><emphasis diffmk:change="added"> + <property diffmk:change="added" moreinfo="none"><diffmk:wrapper diffmk:change="added">Run As > Run On Server</diffmk:wrapper></property> + </emphasis><diffmk:wrapper diffmk:change="added"> and accept the defaults. On the </diffmk:wrapper><emphasis> + <property diffmk:change="added" moreinfo="none"><diffmk:wrapper diffmk:change="added">Add and Remove Projects</diffmk:wrapper></property> + </emphasis><diffmk:wrapper diffmk:change="changed"> page move the created Project to the right and click </diffmk:wrapper><emphasis> + <property diffmk:change="added" moreinfo="none"><diffmk:wrapper diffmk:change="added">Finish</diffmk:wrapper></property><diffmk:wrapper diffmk:change="added">.</diffmk:wrapper></emphasis></para> + + <figure float="0"> + <title><diffmk:wrapper diffmk:change="changed">Deploying the Portlet Application</diffmk:wrapper></title> + <mediaobject> + <imageobject> + <imagedata fileref="images/starting_project/starting_project_13.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para><diffmk:wrapper diffmk:change="added">It will deploy the Portlet Web Application and start </diffmk:wrapper><property moreinfo="none"><diffmk:wrapper diffmk:change="changed">JBoss + AS</diffmk:wrapper></property>.</para> + + <tip diffmk:change="added"> + <title diffmk:change="added"><diffmk:wrapper diffmk:change="added">Tip:</diffmk:wrapper></title> + + <para diffmk:change="added"><diffmk:wrapper diffmk:change="added">You should use </diffmk:wrapper><emphasis diffmk:change="added"><diffmk:wrapper diffmk:change="added">http://localhost:8080/portal</diffmk:wrapper></emphasis><diffmk:wrapper diffmk:change="added"> URL to see your + Portlet in the Browser.</diffmk:wrapper></para> + </tip> + + <para diffmk:change="added"><diffmk:wrapper diffmk:change="added">In the Browser the Portlet looks as follows:</diffmk:wrapper></para> + + <figure float="0"> + <title><diffmk:wrapper diffmk:change="changed">Java Portlet in the Browser Window</diffmk:wrapper></title> + <mediaobject> + <imageobject> + <imagedata fileref="images/starting_project/starting_project_14.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para><diffmk:wrapper diffmk:change="added">Consequently, here you learnt how to create a Dynamic Web Project, add Java Portlet to + it and deploy the project to </diffmk:wrapper><property diffmk:change="added" moreinfo="none"><diffmk:wrapper diffmk:change="added">JBoss Portal</diffmk:wrapper></property><diffmk:wrapper diffmk:change="added">.</diffmk:wrapper></para> + </section> + +</chapter> + + +<chapter diffmk:change="added" id="jsf_portlet" xml:base="file:///home/ochikvina/WORK/for_compare/trunk/portlet/docs/reference/en/modules/jsf_portlet.xml" xreflabel="jsf_portlet"> + <?dbhtml filename="jsf_portlet.html"?> + <title diffmk:change="added"><diffmk:wrapper diffmk:change="added">Creating JSF Portlet</diffmk:wrapper></title> + + <para diffmk:change="added"><diffmk:wrapper diffmk:change="added">This chapter will explain how you can configure JSF Portlet within Dynamic Web + Project and JSF Project by using the wizards </diffmk:wrapper><property diffmk:change="added" moreinfo="none"><diffmk:wrapper diffmk:change="added">JBoss Tools</diffmk:wrapper></property><diffmk:wrapper diffmk:change="added"> provides.</diffmk:wrapper></para> + + <section diffmk:change="added" id="jsf_portlet1"> + <title diffmk:change="added"><diffmk:wrapper diffmk:change="added">Adding JSF Portlet to Dynamic Web Project</diffmk:wrapper></title> + + <para diffmk:change="added"><diffmk:wrapper diffmk:change="added">To add JSF Portlet to a Dynamic Web Project, you should set the Configuration to </diffmk:wrapper><emphasis diffmk:change="added"> + <property diffmk:change="added" moreinfo="none"><diffmk:wrapper diffmk:change="added">JavaServer Faces v1.1 Project</diffmk:wrapper></property> + </emphasis><diffmk:wrapper diffmk:change="added"> or </diffmk:wrapper><emphasis diffmk:change="added"> + <property diffmk:change="added" moreinfo="none"><diffmk:wrapper diffmk:change="added">JavaServer Faces v1.2 Project</diffmk:wrapper></property> + </emphasis><diffmk:wrapper diffmk:change="added"> and configure the JSF Portlet Facets in the </diffmk:wrapper><property diffmk:change="added" moreinfo="none"><diffmk:wrapper diffmk:change="added">New Dynamic Web + Project wizard</diffmk:wrapper></property><diffmk:wrapper diffmk:change="added"> by clicking the </diffmk:wrapper><emphasis diffmk:change="added"> + <property diffmk:change="added" moreinfo="none"><diffmk:wrapper diffmk:change="added">Modify</diffmk:wrapper></property> + </emphasis><diffmk:wrapper diffmk:change="added"> button.</diffmk:wrapper></para> + + <figure float="0"> + <title><diffmk:wrapper diffmk:change="changed">Setting the JSF Configuration</diffmk:wrapper></title> + <mediaobject> + <imageobject> + <imagedata fileref="images/jsf_portlet/jsf_portlet1.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para><diffmk:wrapper diffmk:change="added">On the Project Facets dialog you should select </diffmk:wrapper><property diffmk:change="added" moreinfo="none"><diffmk:wrapper diffmk:change="added">JBoss Core Portlet</diffmk:wrapper></property><diffmk:wrapper diffmk:change="added"> + and </diffmk:wrapper><property diffmk:change="added" moreinfo="none"><diffmk:wrapper diffmk:change="added">JBoss JSF Portlet</diffmk:wrapper></property><diffmk:wrapper diffmk:change="added"> check boxes.</diffmk:wrapper></para> + + <figure diffmk:change="added" float="0"> + <title diffmk:change="added"><diffmk:wrapper diffmk:change="added">Enabling the Portlet Facets</diffmk:wrapper></title> + <mediaobject diffmk:change="added"> + <imageobject diffmk:change="added"> + <imagedata diffmk:change="added" fileref="images/jsf_portlet/jsf_portlet2.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para diffmk:change="added"><diffmk:wrapper diffmk:change="added">Next wizard page is for configuring JSF Capabilities. You can leave everything as it + is here.</diffmk:wrapper></para> + + <figure diffmk:change="added" float="0"> + <title diffmk:change="added"><diffmk:wrapper diffmk:change="added">JSF Capabilities</diffmk:wrapper></title> + <mediaobject diffmk:change="added"> + <imageobject diffmk:change="added"> + <imagedata diffmk:change="added" fileref="images/jsf_portlet/jsf_portlet3.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para diffmk:change="added"><diffmk:wrapper diffmk:change="added">To support Portlets in JSF/Seam applications </diffmk:wrapper><property diffmk:change="added" moreinfo="none"><diffmk:wrapper diffmk:change="added">JBoss Tools</diffmk:wrapper></property><diffmk:wrapper diffmk:change="added"> works + with </diffmk:wrapper><property diffmk:change="added" moreinfo="none"><diffmk:wrapper diffmk:change="added">JBoss Portlet Bridge</diffmk:wrapper></property><diffmk:wrapper diffmk:change="added">. Thus on the next page you should add JSF Portlet + capabilities by pointing to the Portletbridge Runtime location.</diffmk:wrapper></para> + + <figure diffmk:change="added" float="0"> + <title diffmk:change="added"><diffmk:wrapper diffmk:change="added">JSF Capabilities</diffmk:wrapper></title> + <mediaobject diffmk:change="added"> + <imageobject diffmk:change="added"> + <imagedata diffmk:change="added" fileref="images/jsf_portlet/jsf_portlet4.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <tip diffmk:change="added"> + <title diffmk:change="added"><diffmk:wrapper diffmk:change="added">Tip:</diffmk:wrapper></title> + + <para diffmk:change="added"><diffmk:wrapper diffmk:change="added">You can download JBoss Portlet Bridge 1.0.0.B4 from </diffmk:wrapper><ulink diffmk:change="added" url="http://www.jboss.org/portletbridge/download/"><diffmk:wrapper diffmk:change="added">here</diffmk:wrapper></ulink><diffmk:wrapper diffmk:change="added">.</diffmk:wrapper></para> + </tip> + + <para diffmk:change="added"><diffmk:wrapper diffmk:change="added">Next click </diffmk:wrapper><emphasis diffmk:change="added"> + <property diffmk:change="added" moreinfo="none"><diffmk:wrapper diffmk:change="added">Finish</diffmk:wrapper></property> + </emphasis><diffmk:wrapper diffmk:change="added"> to organize the Project.</diffmk:wrapper></para> + <para diffmk:change="added" id="add_jsf_portlet"><diffmk:wrapper diffmk:change="added">To add JSF Portlet to generated project you should call the + </diffmk:wrapper><property diffmk:change="added" moreinfo="none"><diffmk:wrapper diffmk:change="added">Create Portlet wizard</diffmk:wrapper></property><diffmk:wrapper diffmk:change="added"> by navigating to </diffmk:wrapper><emphasis diffmk:change="added"> + <property diffmk:change="added" moreinfo="none"><diffmk:wrapper diffmk:change="added">New > Other > JBoss Tools Web > Portlet > JSF/Seam + Portlet</diffmk:wrapper></property><diffmk:wrapper diffmk:change="added">.</diffmk:wrapper></emphasis></para> + + <figure diffmk:change="added" float="0"> + <title diffmk:change="added"><diffmk:wrapper diffmk:change="added">Calling New Portlet Wizard</diffmk:wrapper></title> + <mediaobject diffmk:change="added"> + <imageobject diffmk:change="added"> + <imagedata diffmk:change="added" fileref="images/jsf_portlet/jsf_portlet5.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para diffmk:change="added"><diffmk:wrapper diffmk:change="added">As you see, the Seam and JSF Portlet wizards are merged into one. We set JSF + Configuration for the project, so default values in this wizard will be set as for a JSF + portlet.</diffmk:wrapper></para> + + <figure diffmk:change="added" float="0"> + <title diffmk:change="added"><diffmk:wrapper diffmk:change="added">Creating JSF Portlet</diffmk:wrapper></title> + <mediaobject diffmk:change="added"> + <imageobject diffmk:change="added"> + <imagedata diffmk:change="added" fileref="images/jsf_portlet/jsf_portlet6.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para diffmk:change="added"><diffmk:wrapper diffmk:change="added">Click </diffmk:wrapper><emphasis diffmk:change="added"> + <property diffmk:change="added" moreinfo="none"><diffmk:wrapper diffmk:change="added">Finish</diffmk:wrapper></property> + </emphasis><diffmk:wrapper diffmk:change="added"> to complete JSF Portlet creation. Now you can deploy the project the same + way as it was </diffmk:wrapper><link diffmk:change="added" linkend="deploying_to_portal"><diffmk:wrapper diffmk:change="added">described above</diffmk:wrapper></link><diffmk:wrapper diffmk:change="added">.</diffmk:wrapper></para> + + <para diffmk:change="added"><diffmk:wrapper diffmk:change="added">In the Browser JSF Portlet looks as follows.</diffmk:wrapper></para> + + <figure float="0"> + <title><diffmk:wrapper diffmk:change="changed">JSF Portlet in the Browser</diffmk:wrapper></title> + <mediaobject> + <imageobject> + <imagedata fileref="images/jsf_portlet/jsf_portlet7.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + </section> + + <section id="jsf_portlet_to_JSF_project"> + <title><diffmk:wrapper diffmk:change="changed">Adding JSF Portlet to JSF Project</diffmk:wrapper></title> + + <para><diffmk:wrapper diffmk:change="added">How to organize a JSF Project you can find out in our </diffmk:wrapper><ulink diffmk:change="added" url="../../jsf_tools_ref_guide/html_single/index.html#new_jsf_project"><diffmk:wrapper diffmk:change="added">JSF Tools Reference Guide</diffmk:wrapper></ulink><diffmk:wrapper diffmk:change="added">. Just + remember to point Target Runtime to JBoss Portal directory location.</diffmk:wrapper></para> + + <figure diffmk:change="added" float="0"> + <title diffmk:change="added"><diffmk:wrapper diffmk:change="added">Creating New JSF Project</diffmk:wrapper></title> + <mediaobject diffmk:change="added"> + <imageobject diffmk:change="added"> + <imagedata diffmk:change="added" fileref="images/jsf_portlet/jsf_portlet8.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para diffmk:change="added"><diffmk:wrapper diffmk:change="added">Before adding a Portlet to the project you should enable necessary facets for it. + Right-click the created project and click </diffmk:wrapper><emphasis> + <property moreinfo="none"><diffmk:wrapper diffmk:change="changed">Preferences</diffmk:wrapper></property> + </emphasis><diffmk:wrapper diffmk:change="added"> to open the </diffmk:wrapper><property diffmk:change="added" moreinfo="none"><diffmk:wrapper diffmk:change="added">Project Preferences</diffmk:wrapper></property><diffmk:wrapper diffmk:change="added"> screen.</diffmk:wrapper></para> + <para diffmk:change="added"><diffmk:wrapper diffmk:change="added">On the </diffmk:wrapper><property diffmk:change="added" moreinfo="none"><diffmk:wrapper diffmk:change="added">Project Facets</diffmk:wrapper></property><diffmk:wrapper diffmk:change="added"> page select the </diffmk:wrapper><emphasis diffmk:change="added"> + <property diffmk:change="added" moreinfo="none"><diffmk:wrapper diffmk:change="added">JBoss Core Portlet</diffmk:wrapper></property> + </emphasis><diffmk:wrapper diffmk:change="added"> and </diffmk:wrapper><emphasis diffmk:change="added"> + <property diffmk:change="added" moreinfo="none"><diffmk:wrapper diffmk:change="added">JBoss JSF Portlet</diffmk:wrapper></property> + </emphasis><diffmk:wrapper diffmk:change="added"> checkboxes. And then the screen will ask you to enable </diffmk:wrapper><emphasis> + <property diffmk:change="added" moreinfo="none"><diffmk:wrapper diffmk:change="added">JavaServer Faces</diffmk:wrapper></property> + </emphasis><diffmk:wrapper diffmk:change="added"> facet as well.</diffmk:wrapper></para> + + <figure diffmk:change="added" float="0"> + <title diffmk:change="added"><diffmk:wrapper diffmk:change="added">Project Facets</diffmk:wrapper></title> + <mediaobject diffmk:change="added"> + <imageobject diffmk:change="added"> + <imagedata diffmk:change="added" fileref="images/jsf_portlet/jsf_portlet9.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para diffmk:change="added"><diffmk:wrapper diffmk:change="added">Notice, </diffmk:wrapper><emphasis diffmk:change="added"> + <property moreinfo="none"><diffmk:wrapper diffmk:change="added">"Further configuration required..."</diffmk:wrapper></property> + </emphasis><diffmk:wrapper diffmk:change="added"> warning appears at the bottom of the screen. It means that you should click + it to configure JSF and JSF Portlet Capabilities in the project.</diffmk:wrapper></para> + + <figure diffmk:change="added" float="0"> + <title diffmk:change="added"><diffmk:wrapper diffmk:change="added">JSF Capabilities</diffmk:wrapper></title> + <mediaobject diffmk:change="added"> + <imageobject diffmk:change="added"> + <imagedata diffmk:change="added" fileref="images/jsf_portlet/jsf_portlet10.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <figure diffmk:change="added" float="0"> + <title diffmk:change="added"><diffmk:wrapper diffmk:change="added">Project Facets</diffmk:wrapper></title> + <mediaobject diffmk:change="added"> + <imageobject diffmk:change="added"> + <imagedata diffmk:change="added" fileref="images/jsf_portlet/jsf_portlet11.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para diffmk:change="added"><diffmk:wrapper diffmk:change="added">After setting the path to Portletbridge Runtime location, click </diffmk:wrapper><emphasis diffmk:change="added"> + <property diffmk:change="added" moreinfo="none"><diffmk:wrapper diffmk:change="added">OK</diffmk:wrapper></property> + </emphasis><diffmk:wrapper diffmk:change="added"> and then </diffmk:wrapper><emphasis diffmk:change="added"> + <property diffmk:change="added" moreinfo="none"><diffmk:wrapper diffmk:change="added">OK</diffmk:wrapper></property> + </emphasis><diffmk:wrapper diffmk:change="added"> again.</diffmk:wrapper></para> + + <para diffmk:change="added"><diffmk:wrapper diffmk:change="added">Now you can add JSF Portlet to the generated JSF Project. How to do it we showed in + </diffmk:wrapper><link diffmk:change="added" linkend="add_jsf_portlet"><diffmk:wrapper diffmk:change="added">the previous section</diffmk:wrapper></link><diffmk:wrapper diffmk:change="added">.</diffmk:wrapper></para> + </section> +</chapter> + + +<chapter diffmk:change="added" id="seam_portlet" xml:base="file:///home/ochikvina/WORK/for_compare/trunk/portlet/docs/reference/en/modules/seam_portlet.xml" xreflabel="seam_portlet"> + <?dbhtml filename="seam_portlet.html"?> + <title diffmk:change="added"><diffmk:wrapper diffmk:change="added">Creating Seam Portlet</diffmk:wrapper></title> + + <para diffmk:change="added"><diffmk:wrapper diffmk:change="added">This chapter covers the steps on how to configure Seam Portlet within Dynamic Web + Project and Seam Project by using the wizards </diffmk:wrapper><property diffmk:change="added" moreinfo="none"><diffmk:wrapper diffmk:change="added">JBoss Tools</diffmk:wrapper></property><diffmk:wrapper diffmk:change="added"> provides.</diffmk:wrapper></para> + + <section diffmk:change="added" id="seam_portlet1"> + <title diffmk:change="added"><diffmk:wrapper diffmk:change="added">Adding Seam Portlet to Dynamic Web Project</diffmk:wrapper></title> + + <para diffmk:change="added"><diffmk:wrapper diffmk:change="added">To add Seam Portlet to a Dynamic Web Project first you should organize New Dynamic Web + Project with the Configuration setting to </diffmk:wrapper><emphasis> + <property moreinfo="none"><diffmk:wrapper diffmk:change="changed">JBoss Seam Portlet Project v2.0</diffmk:wrapper></property>.</emphasis></para> + + <figure float="0"> + <title><diffmk:wrapper diffmk:change="changed">Calling New Portlet Wizard</diffmk:wrapper></title> + <mediaobject> + <imageobject> + <imagedata fileref="images/seam_portlet/seam_portlet1.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para><diffmk:wrapper diffmk:change="added">It will add all needed facets to your project. By clicking the </diffmk:wrapper><emphasis diffmk:change="added"> + <property diffmk:change="added" moreinfo="none"><diffmk:wrapper diffmk:change="added">Modify</diffmk:wrapper></property> + </emphasis><diffmk:wrapper diffmk:change="added"> button you can observe the chosen configuration of facets as well as modify + it. As you can see, all JBoss Portlets are checked.</diffmk:wrapper></para> + + <figure diffmk:change="added" float="0"> + <title diffmk:change="added"><diffmk:wrapper diffmk:change="added">Project Facets</diffmk:wrapper></title> + <mediaobject diffmk:change="added"> + <imageobject diffmk:change="added"> + <imagedata diffmk:change="added" fileref="images/seam_portlet/seam_portlet2.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para diffmk:change="added"><diffmk:wrapper diffmk:change="added">Next wizard pages are for adjusting the Project Web Modules and JSF Configuration. + They include default values, so you can skip them by pressing </diffmk:wrapper><emphasis diffmk:change="added"> + <property diffmk:change="added" moreinfo="none"><diffmk:wrapper diffmk:change="added">Next</diffmk:wrapper></property><diffmk:wrapper diffmk:change="added">.</diffmk:wrapper></emphasis></para> + + <para diffmk:change="added"><diffmk:wrapper diffmk:change="added">On the </diffmk:wrapper><property diffmk:change="added" moreinfo="none"><diffmk:wrapper diffmk:change="added">Seam Facet</diffmk:wrapper></property><diffmk:wrapper diffmk:change="added"> page </diffmk:wrapper><ulink diffmk:change="added" url="../../seam/html_single/index.html#seamFacet"><diffmk:wrapper diffmk:change="added">set + Connection Profile</diffmk:wrapper></ulink><diffmk:wrapper diffmk:change="added"> and hit </diffmk:wrapper><emphasis diffmk:change="added"> + <property moreinfo="none"><diffmk:wrapper diffmk:change="changed">Next</diffmk:wrapper></property>.</emphasis></para> + + <figure diffmk:change="added" float="0"> + <title diffmk:change="added"><diffmk:wrapper diffmk:change="added">Seam Facet Settings</diffmk:wrapper></title> + <mediaobject diffmk:change="added"> + <imageobject diffmk:change="added"> + <imagedata diffmk:change="added" fileref="images/seam_portlet/seam_portlet3.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para diffmk:change="added"><diffmk:wrapper diffmk:change="added">Last wizard page will prompt you to set the path to Portletbridge Runtime + location.</diffmk:wrapper></para> + + <figure diffmk:change="added" float="0"> + <title diffmk:change="added"><diffmk:wrapper diffmk:change="added">Setting the Portletbridge Runtime</diffmk:wrapper></title> + <mediaobject diffmk:change="added"> + <imageobject diffmk:change="added"> + <imagedata diffmk:change="added" fileref="images/seam_portlet/seam_portlet4.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <tip> + <title>Tip:</title> + + <para><diffmk:wrapper diffmk:change="added">Thus you should have JBoss Portlet Bridge downloaded and extracted somewhere on + your hard drive. You can download JBoss Portlet Bridge 1.0.0.B4 from </diffmk:wrapper><ulink diffmk:change="added" url="http://www.jboss.org/portletbridge/download/"><diffmk:wrapper diffmk:change="added">here</diffmk:wrapper></ulink><diffmk:wrapper diffmk:change="added">.</diffmk:wrapper></para> + </tip> + + <para diffmk:change="added"><diffmk:wrapper diffmk:change="added">Now, to add Seam Portlet to the project you should follow to </diffmk:wrapper><emphasis> + <property diffmk:change="added" moreinfo="none"><diffmk:wrapper diffmk:change="added">New > Other > JBoss Tools Web > Portlet > JSF/Seam + Portlet</diffmk:wrapper></property><diffmk:wrapper diffmk:change="added">.</diffmk:wrapper></emphasis><diffmk:wrapper diffmk:change="changed"> This will call the wizard for creating JSF/Seam + Portlets.</diffmk:wrapper></para> + + <figure diffmk:change="added" float="0"> + <title diffmk:change="added"><diffmk:wrapper diffmk:change="added">Calling the Create Portlet Wizard</diffmk:wrapper></title> + <mediaobject diffmk:change="added"> + <imageobject diffmk:change="added"> + <imagedata diffmk:change="added" fileref="images/seam_portlet/seam_portlet5.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para diffmk:change="added"><diffmk:wrapper diffmk:change="added">As we set Seam Configuration for the Dynamic Web Project, the wizard puts the values + as for Seam Portlet.</diffmk:wrapper></para> + + <figure float="0"> + <title><diffmk:wrapper diffmk:change="changed">Creating Seam Portlet</diffmk:wrapper></title> + <mediaobject> + <imageobject> + <imagedata fileref="images/seam_portlet/seam_portlet6.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para><diffmk:wrapper diffmk:change="added">After creating the Seam Portlet, you should </diffmk:wrapper><link diffmk:change="added" linkend="deploying_to_portal"><diffmk:wrapper diffmk:change="added">deploy + the project to JBoss Portal</diffmk:wrapper></link><diffmk:wrapper diffmk:change="added"> and start the Server. In a Browser + you'll see the following:</diffmk:wrapper></para> + + <figure float="0"> + <title><diffmk:wrapper diffmk:change="changed">Seam Portlet in the Browser</diffmk:wrapper></title> + <mediaobject> + <imageobject> + <imagedata fileref="images/seam_portlet/seam_portlet7.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + </section> + + <section diffmk:change="added" id="seam_portlet_to_seam_project"> + <title diffmk:change="added"><diffmk:wrapper diffmk:change="added">Adding Seam Portlet to Seam Project</diffmk:wrapper></title> + + <para><diffmk:wrapper diffmk:change="added">First start a Seam Project by following to </diffmk:wrapper><emphasis diffmk:change="added"> + <property moreinfo="none"><diffmk:wrapper diffmk:change="added">New > Other > Seam > Seam Web Project</diffmk:wrapper></property><diffmk:wrapper diffmk:change="added">. </diffmk:wrapper></emphasis><diffmk:wrapper diffmk:change="added"> On the first + wizard page specify JBoss Portal directory location as </diffmk:wrapper><property diffmk:change="added" moreinfo="none"><diffmk:wrapper diffmk:change="added">Target + Runtime</diffmk:wrapper></property><diffmk:wrapper diffmk:change="added"> and </diffmk:wrapper><emphasis diffmk:change="added"> + <property diffmk:change="added" moreinfo="none"><diffmk:wrapper diffmk:change="added">JBoss Seam Portlet Project v2.0</diffmk:wrapper></property> + </emphasis><diffmk:wrapper diffmk:change="added"> as </diffmk:wrapper><property diffmk:change="added" moreinfo="none"><diffmk:wrapper diffmk:change="added">Configuration</diffmk:wrapper></property><diffmk:wrapper diffmk:change="added">.</diffmk:wrapper></para> + + <figure diffmk:change="added" float="0"> + <title diffmk:change="added"><diffmk:wrapper diffmk:change="added">Project Facets</diffmk:wrapper></title> + <mediaobject diffmk:change="added"> + <imageobject diffmk:change="added"> + <imagedata diffmk:change="added" fileref="images/seam_portlet/seam_portlet8.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para diffmk:change="added"><diffmk:wrapper diffmk:change="added">Next steps will be the same as we did for the Dynamic Web Project in the </diffmk:wrapper><link diffmk:change="added" linkend="seam_portlet1"><diffmk:wrapper diffmk:change="added">Adding Seam Portlet to Dynamic Web Project</diffmk:wrapper></link><diffmk:wrapper diffmk:change="added"> + section.</diffmk:wrapper></para> + </section> +</chapter> + + +<chapter diffmk:change="added" id="portlets_to_nonWTP_projects" xml:base="file:///home/ochikvina/WORK/for_compare/trunk/portlet/docs/reference/en/modules/portlets_to_nonWTP_projects.xml" xreflabel="portlets_to_nonWTP_projects"> + <?dbhtml filename="portlets_to_nonWTP_projects.html"?> + <title diffmk:change="added"><diffmk:wrapper diffmk:change="added">Adding Portlets to non-WTP Projects</diffmk:wrapper></title> + + <para diffmk:change="added"><diffmk:wrapper diffmk:change="added">Starting from </diffmk:wrapper><property diffmk:change="added" moreinfo="none"><diffmk:wrapper diffmk:change="added">JBoss Tools 3.0.0.Beta1</diffmk:wrapper></property><diffmk:wrapper diffmk:change="added"> version the JBoss Portlet + wizards no longer require a WTP project to be able to create Portlets.</diffmk:wrapper></para> + + <note diffmk:change="added"> + <title diffmk:change="added"><diffmk:wrapper diffmk:change="added">Note:</diffmk:wrapper></title> + <para diffmk:change="added"><diffmk:wrapper diffmk:change="added">Please note, if the project does not have the proper portlet API jar's, the generated + classes will have compile errors.</diffmk:wrapper></para> + </note> + + <para diffmk:change="added"><diffmk:wrapper diffmk:change="added">In conclusion, with this document you've learnt how to get started with </diffmk:wrapper><property diffmk:change="added" moreinfo="none"><diffmk:wrapper diffmk:change="added">JBoss + Portal</diffmk:wrapper></property> using <property moreinfo="none">JBoss Tools</property><diffmk:wrapper diffmk:change="changed"> suite of Eclipse plugins. + The above chapters walked you through the steps on how to organize a web project with + portlets which includes a sample staff and deploy it onto the </diffmk:wrapper><property moreinfo="none"><diffmk:wrapper diffmk:change="changed">JBoss + Portal</diffmk:wrapper></property>.</para> + + <para>If you still have questions or suggestions you are always welcome on our <ulink url="http://www.jboss.com/index.html?module=bb&op=viewforum&f=201">Forum</ulink>. Your feedback will be very much appreciated.</para> + +</chapter> + + +</book> Modified: branches/jbosstools-3.0.0.CR1/portlet/docs/reference/en/modules/jsf_portlet.xml =================================================================== --- branches/jbosstools-3.0.0.CR1/portlet/docs/reference/en/modules/jsf_portlet.xml 2008-12-19 19:49:50 UTC (rev 12779) +++ branches/jbosstools-3.0.0.CR1/portlet/docs/reference/en/modules/jsf_portlet.xml 2008-12-19 19:55:55 UTC (rev 12780) @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="UTF-8"?> -<chapter id="jsf_portlet" xreflabel="jsf_portlet"> +<chapter id="jsf_portlet" xreflabel="jsf_portlet" role="new"> <?dbhtml filename="jsf_portlet.html"?> <title>Creating JSF Portlet</title> Modified: branches/jbosstools-3.0.0.CR1/portlet/docs/reference/en/modules/portlets_to_nonWTP_projects.xml =================================================================== --- branches/jbosstools-3.0.0.CR1/portlet/docs/reference/en/modules/portlets_to_nonWTP_projects.xml 2008-12-19 19:49:50 UTC (rev 12779) +++ branches/jbosstools-3.0.0.CR1/portlet/docs/reference/en/modules/portlets_to_nonWTP_projects.xml 2008-12-19 19:55:55 UTC (rev 12780) @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="UTF-8"?> -<chapter id="portlets_to_nonWTP_projects" xreflabel="portlets_to_nonWTP_projects"> +<chapter id="portlets_to_nonWTP_projects" xreflabel="portlets_to_nonWTP_projects" role="new"> <?dbhtml filename="portlets_to_nonWTP_projects.html"?> <title>Adding Portlets to non-WTP Projects</title> Modified: branches/jbosstools-3.0.0.CR1/portlet/docs/reference/en/modules/seam_portlet.xml =================================================================== --- branches/jbosstools-3.0.0.CR1/portlet/docs/reference/en/modules/seam_portlet.xml 2008-12-19 19:49:50 UTC (rev 12779) +++ branches/jbosstools-3.0.0.CR1/portlet/docs/reference/en/modules/seam_portlet.xml 2008-12-19 19:55:55 UTC (rev 12780) @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="UTF-8"?> -<chapter id="seam_portlet" xreflabel="seam_portlet"> +<chapter id="seam_portlet" xreflabel="seam_portlet" role="new"> <?dbhtml filename="seam_portlet.html"?> <title>Creating Seam Portlet</title> Modified: branches/jbosstools-3.0.0.CR1/portlet/docs/reference/en/modules/starting_project.xml =================================================================== --- branches/jbosstools-3.0.0.CR1/portlet/docs/reference/en/modules/starting_project.xml 2008-12-19 19:49:50 UTC (rev 12779) +++ branches/jbosstools-3.0.0.CR1/portlet/docs/reference/en/modules/starting_project.xml 2008-12-19 19:55:55 UTC (rev 12780) @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="UTF-8"?> -<chapter id="starting_project" xreflabel="starting_project"> +<chapter id="starting_project" xreflabel="starting_project" role="updated"> <?dbhtml filename="starting_project.html"?> <title>Starting the Project with JBoss Portal</title>

15 years, 4 months

1
0
0 / 0

JBoss Tools SVN: r12779 - branches/jbosstools-3.0.0.CR1/jbpm/docs/converter_ref/en.

by jbosstools-commits＠lists.jboss.org

Author: smukhina Date: 2008-12-19 14:49:50 -0500 (Fri, 19 Dec 2008) New Revision: 12779 Modified: branches/jbosstools-3.0.0.CR1/jbpm/docs/converter_ref/en/master.xml Log: https://jira.jboss.org/jira/browse/JBDS-324 the latest docs that are done for release 3.0.0.CR1 from trunk are added to branch Modified: branches/jbosstools-3.0.0.CR1/jbpm/docs/converter_ref/en/master.xml =================================================================== --- branches/jbosstools-3.0.0.CR1/jbpm/docs/converter_ref/en/master.xml 2008-12-19 19:47:46 UTC (rev 12778) +++ branches/jbosstools-3.0.0.CR1/jbpm/docs/converter_ref/en/master.xml 2008-12-19 19:49:50 UTC (rev 12779) @@ -17,7 +17,7 @@ <holder>JBoss, a division of Red Hat Inc.</holder> </copyright> <releaseinfo> - Version: 3.0.0.beta1 + Version: 3.0.0.CR1 </releaseinfo> <abstract> <title/>

15 years, 4 months

1
0
0 / 0

JBoss Tools SVN: r12778 - in branches/jbosstools-3.0.0.CR1/hibernatetools/docs/reference/en: modules and 1 other directory.

by jbosstools-commits＠lists.jboss.org

Author: smukhina Date: 2008-12-19 14:47:46 -0500 (Fri, 19 Dec 2008) New Revision: 12778 Added: branches/jbosstools-3.0.0.CR1/hibernatetools/docs/reference/en/master_output.xml Modified: branches/jbosstools-3.0.0.CR1/hibernatetools/docs/reference/en/master.xml branches/jbosstools-3.0.0.CR1/hibernatetools/docs/reference/en/modules/plugins.xml branches/jbosstools-3.0.0.CR1/hibernatetools/docs/reference/en/modules/reverseengineering.xml Log: https://jira.jboss.org/jira/browse/JBDS-324 the latest docs that are done for release 3.0.0.CR1 from trunk are added to branch master_output - the file to build guide versions with highlighted diff markers Modified: branches/jbosstools-3.0.0.CR1/hibernatetools/docs/reference/en/master.xml =================================================================== --- branches/jbosstools-3.0.0.CR1/hibernatetools/docs/reference/en/master.xml 2008-12-19 19:41:47 UTC (rev 12777) +++ branches/jbosstools-3.0.0.CR1/hibernatetools/docs/reference/en/master.xml 2008-12-19 19:47:46 UTC (rev 12778) @@ -40,7 +40,7 @@ </copyright> <releaseinfo> - Version: 3.0.0.beta1 + Version: 3.0.0.CR1 </releaseinfo> Added: branches/jbosstools-3.0.0.CR1/hibernatetools/docs/reference/en/master_output.xml =================================================================== --- branches/jbosstools-3.0.0.CR1/hibernatetools/docs/reference/en/master_output.xml (rev 0) +++ branches/jbosstools-3.0.0.CR1/hibernatetools/docs/reference/en/master_output.xml 2008-12-19 19:47:46 UTC (rev 12778) @@ -0,0 +1,5033 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" +"http://www.docbook.org/xml/4.3/docbookx.dtd" + +[ +<!ENTITY preface SYSTEM "modules/preface.xml"> +<!ENTITY setup SYSTEM "modules/setup.xml"> +<!ENTITY codegenarchitecture SYSTEM "modules/codegenarchitecture.xml"> +<!ENTITY plugins SYSTEM "modules/plugins.xml"> +<!ENTITY ant SYSTEM "modules/ant.xml"> +<!ENTITY reveng SYSTEM "modules/reverseengineering.xml"> +<!ENTITY codegen SYSTEM "modules/codegen.xml"> + +<!ENTITY seamlink "../../seam/html_single/index.html"> +<!ENTITY aslink "../../as/html_single/index.html"> +<!ENTITY esblink "../../esb_ref_guide/html_single/index.html"> +<!ENTITY gsglink "../../GettingStartedGuide/html_single/index.html"> +<!ENTITY hibernatelink "../../hibernatetools/html_single/index.html"> +<!ENTITY jbpmlink "../../jbpm/html_single/index.html"> +<!ENTITY jsflink "../../jsf/html_single/index.html"> +<!ENTITY jsfreflink "../../jsf_tools_ref_guide/html_single/index.html"> +<!ENTITY jsftutoriallink "../../jsf_tools_tutorial/html_single/index.html"> +<!ENTITY strutsreflink "../../struts_tools_ref_guide/html_single/index.html"> +<!ENTITY strutstutoriallink "../../struts_tools_tutorial/html_single/index.html"> + +]><book lang="en" xmlns:diffmk="http://diffmk.sf.net/ns/diff"> + <bookinfo> + <title>Hibernate Tools Reference Guide</title> + + <author><firstname>Max</firstname><surname>Andersen</surname><email>max.andersen(a)jboss.com</email></author> + <author><firstname>Olga</firstname><surname>Chikvina</surname></author> + <author><firstname>Svetlana</firstname><surname>Mukhina</surname><email>smukhina(a)exadel.com</email></author> + + <pubdate>April 2008</pubdate> + <copyright> + <year>2007</year> + <year>2008</year> + <holder>JBoss, a division of Red Hat Inc.</holder> + </copyright> + + <releaseinfo><diffmk:wrapper diffmk:change="changed"> + Version: 3.0.0.CR1 + </diffmk:wrapper></releaseinfo> + + + <mediaobject> + <imageobject> + <imagedata fileref="images/hibernate_logo_a.png" format="PNG"></imagedata> + </imageobject> + </mediaobject> + +<abstract> + <title></title> + <para> + <ulink url="http://download.jboss.org/jbosstools/nightly-docs/en/hibernatetools/pdf/H...">PDF version</ulink> + </para> +</abstract> + + </bookinfo> + <toc></toc> + + +<chapter id="preface" xml:base="file:///home/ochikvina/WORK/for_compare/trunk/hibernatetools/docs/reference/en/modules/preface.xml"> + + <title>Preface</title> + + <para><property moreinfo="none">Hibernate Tools</property> is a toolset for <ulink url="http://www.hibernate.org/6.html">Hibernate 3</ulink> and <ulink url="http://www.hibernate.org/27.html">related projects</ulink>. The tools provide Ant + tasks and Eclipse plugins for performing reverse engineering, code generation, visualization + and interaction with Hibernate.</para> + + <section id="hibernate_key_features"> + <title>Key Features</title> + + <para>First, we propose to look through the list of key features that you can benefit from + if you start using <property moreinfo="none">Hibernate Tools</property>.</para> + + <table> + <title>Key Functionality for Hibernate Tools</title> + <tgroup cols="3"> + + <colspec align="left" colnum="1" colwidth="1*"></colspec> + <colspec colnum="2" colwidth="5*"></colspec> + <colspec align="left" colnum="3" colwidth="1*"></colspec> + + <thead> + <row> + <entry>Feature</entry> + <entry>Benefit</entry> + <entry>Chapter</entry> + </row> + </thead> + + <tbody> + + <row> + <entry> + <para>Code Generation through Ant Task</para> + </entry> + <entry> + <para>Allows to execute mapping or Java code generation from reverse + engineering, schema generation and generation of other artifacts + during the build process.</para> + </entry> + <entry><link linkend="ant">ant task</link></entry> + </row> + + <row> + <entry> + <para>Wizards for creation + purposes and code + generation</para> + </entry> + <entry> + <para> A set of wizards are provided with the Hibernate Eclipse tools to + quickly create common Hibernate files such as configuration + (cfg.xml) files, mapping files and revenge.xml as well. Code + Generation wizard helps to generate a series of various artifacts, + there is even support for completely reverse engineer an existing + database schema.</para> + </entry> + <entry> <link linkend="map_file_wizard">hibernate mapping file</link> + <link linkend="hib_config_file">hibernate configuration file</link> + <link linkend="code_gen">code generation</link> + </entry> + </row> + + + <row> + <entry> + <para> + Mapping and Configuration files + Editors + </para> + </entry> + <entry> + <para>Support auto-completion and syntax highlighting. Editors also + support semantic auto-completion for class names and property/field + names, making it much more versatile than a normal XML + editor.</para> + </entry> + <entry> <link linkend="map_config_editor">mapping and configuration files editors</link></entry> + </row> + + <row> + <entry> + <para>Tools for organizing and controlling Reverse Engineering</para> + </entry> + <entry> + <para>Code Generation wizard provides powerful functionality for + generating a series of various artifacts like domain model classes, + mapping files, annotated EJB3 entity beans, etc. and reveng.xml file + editor allows to control this processes.</para> + </entry> + <entry><link linkend="code_gen">code generation</link> + <link linkend="rev_xml_editor">reveng.xml editor</link></entry> + </row> + + <row> + <entry> + <para>Hibernate Console</para> + </entry> + <entry> + <para>It is a new perspective in Eclipse which provides an overview of + your Hibernate Console configurations, were you also can get an + interactive view of your persistent classes and their relationships. + The console allows you to execute HQL queries against your database + and browse the result directly in Eclipse.</para> + </entry> + <entry><link linkend="hib_console">hibernate console</link></entry> + </row> + + <row> + <entry> + <para>Functional Mapping Diagram</para> + </entry> + <entry> + <para>Makes possible to visualize structure of entities and + relationships between them.</para> + </entry> + <entry><link linkend="map_diagram">mapping diagram</link></entry> + </row> + + + <row> + <entry> + <para>Eclipse JDT integration</para> + </entry> + <entry> + <para>Hibernate Tools integrates into the Java code completion and build + support of Java in Eclipse. This gives you code completion of HQL + inside Java code. Additionally, Hibernate Tools will add problem + markers if your queries are not valid against the console + configuration associated with the project.</para> + </entry> + </row> + + </tbody> + </tgroup> + </table> + </section> + + <section> + <title>Other relevant resources on the topic</title> + + <para diffmk:change="added"><diffmk:wrapper diffmk:change="added">Hibernate Tools page on the </diffmk:wrapper><ulink diffmk:change="added" url="http://www.hibernate.org/255.html"><diffmk:wrapper diffmk:change="added">hibernate.org</diffmk:wrapper></ulink><diffmk:wrapper diffmk:change="added">.</diffmk:wrapper></para> + <para>All JBoss Developer Studio/JBoss Tools documentation you can find <ulink url="http://www.jboss.com/products/devstudio/docs">here</ulink>.</para> + <para>The latest documentation builds are available <ulink url="http://download.jboss.org/jbosstools/nightly-docs/">here</ulink>.</para> + </section> + +</chapter> + + +<chapter id="setup" xml:base="file:///home/ochikvina/WORK/for_compare/trunk/hibernatetools/docs/reference/en/modules/setup.xml"> + <title>Download and install Hibernate Tools</title> + + <para><property moreinfo="none">Hibernate Tools</property> can be used "standalone" via Ant + 1.6.x or fully integrated into an Eclipse 3.3.x + WTP 2.x based IDE, such as <property moreinfo="none">JBoss + Tools</property> or a default Eclipse 3.3.x + WTP 2.x installation. The following describes + the install steps in these environments.</para> + + <section> + <title>JBoss Tools</title> + + <para><property moreinfo="none">JBoss Tools 2.x</property> includes <property moreinfo="none">Hibernate Tools</property> and + thus nothing is required besides <ulink url="http://labs.jboss.com/tools/download/index.html">downloading</ulink> and <ulink url="../../GettingStartedGuide/html_single/index.html#JBossToolsInstall">installing JBoss Tools</ulink>. If you need to update to a newer version of the + <property moreinfo="none">Hibernate Tools</property> just follow the instructions in the Eclipse IDE + section.</para> + </section> + + <section> + <title>Eclipse IDE</title> + + <para>To install into any <property moreinfo="none">Eclipse 3.3.x</property> based Eclipse IDE you can either + download the <property moreinfo="none">Hibernate Tools</property> distribution from the <ulink url="http://www.hibernate.org/6.html">Hibernate website</ulink> or use the <ulink url="http://download.jboss.org/jbosstools/updates/stable/">JBoss Tools Update Site</ulink> + (see also <ulink url="http://tools.hibernate.org">http://tools.hibernate.org</ulink> for links + to the update site).</para> + + <para>If you download the <property moreinfo="none">Hibernate Tools</property> distribution you need to place + the <emphasis> + <property moreinfo="none">/plugins</property> + </emphasis> and <emphasis> + <property moreinfo="none">/feature</property> + </emphasis> directory into your eclipse directory or eclipse extensions directory. Sometimes + Eclipse does not automatically detect new plugins and thus the tools will not be activated. To + ensure eclipse sees these changes just clean up the cached plugin information by running eclipse with the <emphasis> + <property moreinfo="none">-clean</property></emphasis> option, e.g. <emphasis> + <property moreinfo="none">eclipse + -clean</property>.</emphasis> Using the updatesite does not require any additional steps.</para> + + <note> + <title>Note:</title> + <para>If you need more basic instructions on installing plugins and general usage of eclipse + then check out <ulink url="https://eclipse-tutorial.dev.java.net/">https://eclipse-tutorial.dev.java.net/</ulink> and especially <ulink url="https://eclipse-tutorial.dev.java.net/visual-tutorials/updatemanager.html">https://eclipse-tutorial.dev.java.net/visual-tutorials/updatemanager.html</ulink> which + covers using the update manager.</para> + </note> + + <section> + <title>Usage of Eclipse WTP</title> + + <para>The <property moreinfo="none">Hibernate Tools</property> plugins currently use <property moreinfo="none">WTP + 2.x</property> which at this time is the latest stable release from the Eclipse Webtools + project.</para> + + <para>Because the WTP project not always have had proper versioning of their plugins there + might exist WTP plugins in your existing eclipse directory from other Eclipse based projects + that are from an earlier WTP release but has either the same version number or higher. It is + thus recommended that if you have issues with WTP provided features to try and install the + plugins on a clean install of eclipse to ensure there are no version collisions.</para> + + </section> + </section> + + <section> + <title>Ant</title> + + <para>To use the tools via Ant you need the <emphasis> + <property moreinfo="none">hibernate-tools.jar</property> + </emphasis> and associated libraries. The libraries are included in the distribution from the + Hibernate website and the Eclipse updatesite. The libraries are located in the eclipse plugins + directory at <emphasis> + <property moreinfo="none">/plugins/org.hibernate.eclipse.x.x.x/lib/tools/</property></emphasis>. These libraries are 100% + independent from the eclipse platform. How to use these via ant tasks are described in the + <link linkend="ant">Ant Tools</link> chapter.</para> + </section> +</chapter> + + +<chapter id="codegenarchitecture" xml:base="file:///home/ochikvina/WORK/for_compare/trunk/hibernatetools/docs/reference/en/modules/codegenarchitecture.xml"> + <title>Code generation architecture</title> + + <para>The code generation mechanism in the <property moreinfo="none">Hibernate Tools</property> consists of a few + core concepts. This section explains their overall structure which are the same for the Ant and + Eclipse tools.</para> + + <section> + <title>Hibernate Meta Model</title> + + <para>The meta model is the model used by Hibernate Core to perform its object relational + mapping. The model includes information about tables, columns, classes, properties, + components, values, collections etc. The API is in <literal moreinfo="none">org.hibernate.mapping</literal> + and its main entry point is the <literal moreinfo="none">Configuration</literal> class, the same class that is + used to build a session factory.</para> + + <para>The model represented by the <literal moreinfo="none">Configuration</literal> class can be build in many + ways. The following list the currently supported ones in <property moreinfo="none">Hibernate Tools</property>. </para> + + <para> + <itemizedlist> + <listitem> + <para>A Core configuration uses Hibernate Core and supports reading <emphasis> + <property moreinfo="none">hbm.xml</property> + </emphasis> files, requires a <emphasis> + <property moreinfo="none">hibernate.cfg.xml</property> + </emphasis>. Named core in Eclipse and <emphasis> + <property moreinfo="none"> + <literal moreinfo="none"><configuration></literal> + </property> + </emphasis> in ant.</para> + </listitem> + + <listitem> + <para>An Annotation configuration uses Hibernate Annotations and supports <emphasis> + <property moreinfo="none">hbm.xml</property> + </emphasis> and annotated classes, requires a <emphasis> + <property moreinfo="none">hibernate.cfg.xml</property> + </emphasis>. Named annotations in Eclipse and <emphasis> + <property moreinfo="none"> + <literal moreinfo="none"><annotationconfiguration></literal> + </property> + </emphasis> in ant.</para> + </listitem> + + <listitem> + <para>A JPA configuration uses a Hibernate EntityManager and supports <emphasis> + <property moreinfo="none">hbm.xml</property> + </emphasis> and annotated classes requires that the project has a <emphasis> + <property moreinfo="none">META-INF/persistence.xml</property> + </emphasis> in its classpath. Named JPA in Eclipse and <emphasis> + <property moreinfo="none"> + <literal moreinfo="none"><jpaconfiguration></literal> + </property> + </emphasis> in ant.</para> + </listitem> + + <listitem> + <para>A JDBC configuration uses <property moreinfo="none">Hibernate Tools</property> reverse engineering + and reads its mappings via JDBC metadata + additional reverse engineering files + (reveng.xml). Automatically used in Eclipse when doing reverse engineering from JDBC and + named <emphasis> + <property moreinfo="none"> + <literal moreinfo="none"><jdbcconfiguration></literal> + </property> + </emphasis> in ant.</para> + </listitem> + </itemizedlist> + </para> + + <para>In most projects you will normally use only one of the Core, Annotation or JPA + configuration and possibly the JDBC configuration if you are using the reverse engineering + facilities of <property moreinfo="none">Hibernate Tools</property>. </para> + + <note> + <title>Note:</title> + <para>No matter which Hibernate Configuration type you are using <property moreinfo="none">Hibernate + Tools</property> supports them.</para> + </note> + + <para>The following drawing illustrates the core concepts:</para> + + <para> + <figure float="0"> + <title>Hibernate Core Concepts</title> + <mediaobject> + <imageobject role="fo"> + <imagedata fileref="images/code_generation/code_generation_1.png" format="PNG"></imagedata> + </imageobject> + + <imageobject role="html"> + + <imagedata align="center" fileref="images/code_generation/code_generation_1.png" format="PNG"></imagedata> + </imageobject> + </mediaobject> + </figure> + </para> + + <para>The code generation is done based on the Configuration model no matter which type of + configuration have been used to create the meta model, and thus the code generation is + independent on the source of the meta model and represented via Exporters.</para> + </section> + + <section> + <title>Exporters</title> + + <para>Code generation is done in so called Exporters. An <literal moreinfo="none">Exporter</literal> is handed a + Hibernate Meta Model represented as a <literal moreinfo="none">Configuration</literal> instance and it is then + the job of the exporter to generate a set of code artifacts.</para> + + <para>The tools provides a default set of Exporter's which can be used in both Ant and the + Eclipse UI. Documentation for these Exporters is in the <link linkend="ant">Ant Tools</link> + and <link linkend="plugins">Eclipse Plugins</link> chapters.</para> + + <para>Users can provide their own customer Exporter's, either by custom classes implementing the + Exporter interface or simply be providing custom templates. This is documented at <xref linkend="hbmtemplate"></xref></para> + </section> +</chapter> + + +<chapter id="plugins" xml:base="file:///home/ochikvina/WORK/for_compare/trunk/hibernatetools/docs/reference/en/modules/plugins.xml"> + <title>Eclipse Plugins</title> + + <para>This chapter will introduce you to the functionality that <property moreinfo="none">Hibernate + Tools</property> provide within Eclipse. That is a set of wizards and editors for simplifying + the work with <property moreinfo="none">Hibernate</property>.</para> + + <section> + <title>Introduction</title> + + <para>Hibernate Eclipse Tools include wizards for creating Hibernate mapping files, + configuration files (.cfg.xml), revenge.xml as well as wizards for adjusting Console + Configuration and Code Generation. Special structured and XML editors, editors for executing + HQL and Criteria queries are also provided in Hibernate Console. Refer to <link linkend="hibernate_key_features">Key Features</link> section to find all benefits that you + can take advantage of while using the tools within Eclipse.</para> + + <note> + <title>Note:</title> + <para>Please note that these tools do not try to hide any functionality of + <property moreinfo="none">Hibernate</property>. The tools make working with <property moreinfo="none">Hibernate</property> + easier, but you are still encouraged/required to read the <ulink url="http://www.hibernate.org/5.html">Hibernate Documentation</ulink> to fully utilize + <property moreinfo="none">Hibernate Tools</property> and especially <property moreinfo="none">Hibernate</property> it + self.</para> + </note> + </section> + + <section id="map_file_wizard"> + <title>Creating a Hibernate Mapping File</title> + + <para>Hibernate mapping files are used to specify how your objects are related to database + tables.</para> + + <para>For creating a skeleton mapping file, i. e. any <emphasis> + <property moreinfo="none">.hbm.xml</property> + </emphasis>, Hibernate Tools provide a basic wizard which you can bring up by navigating <emphasis> + <property moreinfo="none">New > Hibernate XML mapping file</property>.</emphasis></para> + + <figure float="0"> + <title>Hibernate XML Mapping File Wizard</title> + + <mediaobject> + <imageobject> + <imagedata fileref="images/plugins/plugins_0.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>At first you'll be asked to specify the location and the name for a new mapping + file. On the next dialog you should type or browse the class to map.</para> + <figure float="0"> + <title>Specifying the Class to Map</title> + + <mediaobject> + <imageobject> + <imagedata fileref="images/plugins/plugins_0_a.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + <para>Pressing finish creates the file and opens it in the <link linkend="map_config_struct_editor">structured hbm.xml editor</link>.</para> + + <para> If you start the wizard from the selected class, all values will be detected there + automatically.</para> + + <figure float="0"> + <title>Creating Mapping File for Selected Class</title> + + <mediaobject> + <imageobject> + <imagedata fileref="images/plugins/plugins_0_b.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + </section> + + <section id="hib_config_file"> + <title>Creating a Hibernate Configuration File</title> + + <para>To be able to reverse engineer, prototype queries, and of course to simply use + <property moreinfo="none">Hibernate Core</property> a <emphasis> + <property moreinfo="none">hibernate.properties</property> + </emphasis> or <emphasis> + <property moreinfo="none">hibernate.cfg.xml</property> + </emphasis> file is needed. The <property moreinfo="none">Hibernate Tools</property> provide a wizard for + generating the <emphasis> + <property moreinfo="none">hibernate.cfg.xml</property> + </emphasis> file if you do not already have such one.</para> + + <para>Start the wizard by clicking <emphasis> + <property moreinfo="none">New > Other (Ctrl+N)</property> + </emphasis>, then <emphasis> + <property moreinfo="none">Hibernate > Hibernate Configuration File (cfg.xml)</property> + </emphasis> and press <emphasis> + <property moreinfo="none">Next</property> + </emphasis>. After selecting the wanted location for the <emphasis> + <property moreinfo="none">hibernate.cfg.xml</property> + </emphasis> file, you will see the following page:</para> + + <figure float="0"> + <title>Hibernate Configuration File Wizard</title> + <mediaobject> + <imageobject role="fo"> + <imagedata align="center" fileref="images/plugins/plugins_1.png" format="PNG"></imagedata> + </imageobject> + + <imageobject role="html"> + <imagedata align="center" fileref="images/plugins/plugins_1.png" format="PNG"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <note> + <title>Note:</title> + <para>The contents in the combo boxes for the JDBC driver class and JDBC URL change + automatically, depending on the Dialect and actual driver you have chosen.</para> + </note> + + <para>Enter your configuration information in this dialog. Details about the configuration + options can be found in <ulink url="http://docs.jboss.org/ejb3/app-server/Hibernate3/reference/en/html_single">Hibernate + Reference Documentation</ulink>.</para> + + <para>Press <emphasis> + <property moreinfo="none">Finish</property> + </emphasis> to create the configuration file, after optionally creating a Console + configuration, the <emphasis> + <property moreinfo="none">hibernate.cfg.xml</property> + </emphasis> will be automatically opened in an editor. The last option <emphasis> + <property moreinfo="none">Create Console Configuration</property> + </emphasis> is enabled by default and when enabled, it will automatically use the <emphasis> + <property moreinfo="none">hibernate.cfg.xml</property> + </emphasis> for the basis of a Console configuration.</para> + </section> + + <section id="console_conf"> + <title>Creating a Hibernate Console Configuration</title> + + <para>A Console configuration describes how the <property moreinfo="none">Hibernate plugin</property> should + configure <property moreinfo="none">Hibernate</property> and what configuration files, including which + classpath are needed to load the POJO's, JDBC drivers etc. It is required to make usage of + query prototyping, reverse engineering and code generation. You can have multiple named + console configurations. Normally you would just need one per project, but more is definitely + possible if your project requires this.</para> + + <para>You create a console configuration by running the <property moreinfo="none">Console Configuration + Wizard</property>, shown in the following screenshot. The same wizard will also be used if you + are coming from the <emphasis> + <property moreinfo="none">hibernate.cfg.xml</property> + </emphasis> wizard and had enabled <emphasis> + <property moreinfo="none">Create Console Configuration</property> + </emphasis>.</para> + + <note> + <title>Note:</title> + <para>The wizard will look at the current selection in the IDE and try and auto-detect the + settings which you then can just approve or modify to suit your needs.</para> + </note> + <para></para> + + <para>The dialog consists of five tabs: </para> + + <itemizedlist> + <listitem> + <para><emphasis> + <property moreinfo="none">Main</property> + </emphasis> for the basic/required settings</para> + </listitem> + </itemizedlist> + + <figure float="0"> + <title> Creating Hibernate Console Configuration</title> + <mediaobject> + <imageobject role="fo"> + <imagedata align="center" fileref="images/plugins/plugins_2.png" format="PNG"></imagedata> + </imageobject> + + <imageobject role="html"> + <imagedata align="center" fileref="images/plugins/plugins_2.png" format="PNG"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>The following table describes the available settings on the <emphasis> + <property moreinfo="none">Main</property> + </emphasis> tab. The wizard can automatically detect default values for most of these if you + started the wizard with the relevant java project or resource selected.</para> + + <table> + <title>Hibernate Console Configuration Parameters</title> + + <tgroup cols="3"> + <colspec align="left" colnum="1" colwidth="1*"></colspec> + + <colspec colnum="2" colwidth="3*"></colspec> + + <colspec align="left" colnum="3" colwidth="1*"></colspec> + + <thead> + <row> + <entry align="center"> + <para>Parameter</para> + </entry> + + <entry align="center"> + <para>Description</para> + </entry> + + <entry align="center"> + <para>Auto detected value</para> + </entry> + </row> + </thead> + + <tbody> + <row> + <entry> + <para>Name</para> + </entry> + + <entry> + <para>The unique name of the console configuration</para> + </entry> + + <entry> + <para>Name of the selected project</para> + </entry> + </row> + + <row> + <entry> + <para>Type</para> + </entry> + + <entry> + <para>Choose between "Core", "Annotations" and + "JPA". Note that the two latter requires running Eclipse IDE with + a JDK 5 runtime, otherwise you will get classloading and/or version errors.</para> + </entry> + + <entry> + <para>No default value</para> + </entry> + </row> + + <row> + <entry> + <para>Project</para> + </entry> + + <entry> + <para>The name of a java project which classpath should be used in the console + configuration</para> + </entry> + + <entry> + <para>Name of the selected project</para> + </entry> + </row> + + <row> + <entry> + <para>Database connection</para> + </entry> + + <entry> + <para>DTP provided connection that you can use instead of what is in cfg.xml and jpa + persistence.xml. It's possible to use already configured connection or + specify a new one here.</para> + </entry> + + <entry> + <para>[Hibernate Configured connection]</para> + </entry> + </row> + + <row> + <entry> + <para>Property file</para> + </entry> + + <entry> + <para>Path to a hibernate.properties file</para> + </entry> + + <entry> + <para>First hibernate.properties file found in the selected project</para> + </entry> + </row> + + <row> + <entry> + <para>Configuration file</para> + </entry> + + <entry> + <para>Path to a hibernate.cfg.xml file</para> + </entry> + + <entry> + <para>First hibernate.cfg.xml file found in the selected project</para> + </entry> + </row> + + <row> + <entry> + <para>Persistence unit</para> + </entry> + + <entry> + <para>Name of the persistence unit to use</para> + </entry> + + <entry> + <para>No default value (lets Hibernate Entity Manager find the persistence + unit)</para> + </entry> + </row> + + </tbody> + </tgroup> + </table> + + <tip> + <title>Tip:</title> + + <para>The two latter settings are normally not required if you specify a project and it has <emphasis> + <property moreinfo="none"> + <literal moreinfo="none"> /hibernate.cfg.xml </literal> + </property> + </emphasis> or <emphasis> + <property moreinfo="none"> + <literal moreinfo="none">/META-INF/persistence.xml</literal> + </property> + </emphasis> in its project classpath.</para> + </tip> + + + <itemizedlist> + <listitem> + <para> + <emphasis> + <property moreinfo="none">Options</property> + </emphasis> for the additional/optional settings</para> + </listitem> + </itemizedlist> + + <figure float="0"> + <title>Options Tab of the Console Configuration Wizard</title> + + <mediaobject> + <imageobject> + <imagedata fileref="images/plugins/plugins_2_a.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>The next table describes Hibernate Console Configuration options available on the <emphasis> + <property moreinfo="none">Options</property> + </emphasis> tab.</para> + + <table> + <title>Hibernate Console Configuration Options</title> + + <tgroup cols="3"> + <colspec align="left" colnum="1" colwidth="1*"></colspec> + + <colspec colnum="2" colwidth="3*"></colspec> + + <colspec align="left" colnum="3" colwidth="1*"></colspec> + + <thead> + <row> + <entry align="center"> + <para>Parameter</para> + </entry> + + <entry align="center"> + <para>Description</para> + </entry> + + <entry align="center"> + <para>Auto detected value</para> + </entry> + </row> + </thead> + + <tbody> + <row> + <entry> + <para>Naming strategy</para> + </entry> + + <entry> + <para>Fully qualified classname of a custom NamingStrategy. Only required if you use a + special naming strategy.</para> + </entry> + + <entry> + <para>No default value</para> + </entry> + </row> + + <row> + <entry> + <para>Entity resolver</para> + </entry> + + <entry> + <para>Fully qualified classname of a custom EntityResolver. Only required if you have + special xml entity includes in your mapping files.</para> + </entry> + + <entry> + <para>No default value</para> + </entry> + </row> + + </tbody> + </tgroup> + </table> + + <itemizedlist> + <listitem> + <para><emphasis> + <property moreinfo="none">Classpath</property> + </emphasis> for classpath</para> + </listitem> + </itemizedlist> + + <figure float="0"> + <title>Specifying Classpath in Hibernate Console Configuration</title> + <mediaobject> + <imageobject role="fo"> + <imagedata align="center" fileref="images/plugins/plugins_3.png" format="PNG"></imagedata> + </imageobject> + + <imageobject role="html"> + <imagedata align="center" fileref="images/plugins/plugins_3.png" format="PNG"></imagedata> + </imageobject> + + </mediaobject> + </figure> + + <para>The following table specifies the parameters of the Classpath tab of the wizard.</para> + + <table> + <title>Hibernate Console Configuration Classpath</title> + + <tgroup cols="3"> + <colspec align="left" colnum="1" colwidth="1*"></colspec> + + <colspec colnum="2" colwidth="3*"></colspec> + + <colspec colnum="3" colwidth="1*"></colspec> + + <thead> + <row> + <entry align="center"> + <para>Parameter</para> + </entry> + + <entry align="center"> + <para>Description</para> + </entry> + + <entry align="center"> + <para>Auto detected value</para> + </entry> + </row> + </thead> + + <tbody> + <row> + <entry> + <para>Classpath</para> + </entry> + + <entry> + <para>The classpath for loading POJO and JDBC drivers; only needed if the default + classpath of the Project does not contain the required classes. Do not add Hibernate + core libraries or dependencies, they are already included. If you get ClassNotFound + errors then check this list for possible missing or redundant + directories/jars.</para> + </entry> + + <entry> + <para>Empty</para> + </entry> + </row> + + <row> + <entry> + <para>Include default classpath from project</para> + </entry> + + <entry> + <para>When enabled the project classpath will be appended to the classpath specified + above</para> + </entry> + + <entry> + <para>Enabled</para> + </entry> + </row> + + </tbody> + </tgroup> + </table> + + <itemizedlist> + <listitem> + <para><emphasis> + <property moreinfo="none">Mappings</property> + </emphasis> for additional mappings</para> + </listitem> + </itemizedlist> + + <figure float="0"> + <title>Specifying additional Mappings in Hibernate Console Configuration</title> + <mediaobject> + <imageobject role="fo"> + <imagedata align="center" fileref="images/plugins/plugins_4.png" format="PNG"></imagedata> + </imageobject> + + <imageobject role="html"> + <imagedata align="center" fileref="images/plugins/plugins_4.png" format="PNG"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>Parameters of the Mappings tab of the <property moreinfo="none">Hibernate Console Configuration + wizard</property> are explained below:</para> + <table> + <title>Hibernate Console Configuration Mappings</title> + + <tgroup cols="3"> + <colspec align="left" colnum="1" colwidth="1*"></colspec> + + <colspec colnum="2" colwidth="3*"></colspec> + + <colspec colnum="3" colwidth="1*"></colspec> + + <thead> + <row> + <entry align="center"> + <para>Parameter</para> + </entry> + + <entry align="center"> + <para>Description</para> + </entry> + + <entry align="center"> + <para>Auto detected value</para> + </entry> + </row> + </thead> + + <tbody> + <row> + <entry> + <para>Mapping files </para> + </entry> + + <entry> + <para>List of additional mapping files that should be loaded. Note: A + hibernate.cfg.xml or persistence.xml can also contain mappings. Thus if these are + duplicated here, you will get "Duplicate mapping" errors when using the console + configuration.</para> + </entry> + + <entry> + <para>empty</para> + </entry> + </row> + </tbody> + </tgroup> + </table> + + <itemizedlist> + <listitem> + <para>and the last tab <emphasis> + <property moreinfo="none">Common</property> + </emphasis></para> + </listitem> + </itemizedlist> + + <figure float="0"> + <title>Common Tab of the Console Configuration Wizard</title> + + <mediaobject> + <imageobject> + <imagedata fileref="images/plugins/plugins_4_a.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>It allows to define general aspects of the launch configuration including storage + location, console encoding and some others.</para> + + <para>Clicking <emphasis> + <property moreinfo="none">Finish</property> + </emphasis> creates the configuration and shows it in the <property moreinfo="none">Hibernate Configurations + view</property>.</para> + + <figure float="0"> + <title>Console Overview</title> + <mediaobject> + <imageobject role="fo"> + <imagedata align="center" fileref="images/plugins/plugins_5.png" format="PNG"></imagedata> + </imageobject> + + <imageobject role="html"> + <imagedata align="center" fileref="images/plugins/plugins_5.png" format="PNG"></imagedata> + </imageobject> + + </mediaobject> + </figure> + </section> + + <section> + <title>Reverse Engineering and Code Generation</title> + + <para>A "click-and-generate" reverse engineering and code generation facility is available. This + facility allows you to generate a range of artifacts based on database or an already existing + Hibernate configuration, be that mapping files or annotated classes. Some of these are POJO + Java source file, Hibernate <emphasis> + <property moreinfo="none">.hbm.xml</property> + </emphasis>, <emphasis> + <property moreinfo="none">hibernate.cfg.xml</property> + </emphasis> generation and schema documentation.</para> + + <para>To start working with this process, start the <property moreinfo="none">Hibernate Code + Generation</property> which is available in the toolbar via the <property moreinfo="none">Hibernate</property> + icon or via the <emphasis> + <property moreinfo="none">Run > Hibernate Code Generation</property> + </emphasis> menu item.</para> + + <section id="code_gen"> + <title>Code Generation Launcher</title> + + <para>When you click on <emphasis> + <property moreinfo="none">Open Hibernate Code Generation Dialog...</property> + </emphasis> the standard Eclipse launcher dialog will appear. In this dialog you can create, + edit and delete named Hibernate code generation "launchers".</para> + + <figure float="0" id="hib_code_gen"> + <title>Getting Hibernate Code Generation Wizard</title> + <mediaobject> + <imageobject role="fo"> + <imagedata fileref="images/plugins/plugins_6.png" format="PNG"></imagedata> + </imageobject> + + <imageobject role="html"> + <imagedata align="center" fileref="images/plugins/plugins_6.png" format="PNG"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para></para> + + <figure float="0"> + <title>Hibernate Code Generation Wizard</title> + <mediaobject> + <imageobject role="fo"> + <imagedata align="center" fileref="images/plugins/plugins_7.png" format="PNG" scale="80"></imagedata> + </imageobject> + + <imageobject role="html"> + <imagedata align="center" fileref="images/plugins/plugins_7.png" format="PNG"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>The first time you create a code generation launcher you should give it a meaningful + name, otherwise the default prefix <emphasis> + <property moreinfo="none">New_Generation</property> + </emphasis> will be used.</para> + + <tip> + <title>Tip:</title> + <para>The "At least one exporter option must be selected" is just a + warning stating that for this launch to work you need to select an exporter on the + Exporter tab. When an exporter has been selected the warning will disappear.</para> + </tip> + + <para>The dialog also have the standard tabs <emphasis> + <property moreinfo="none">Refresh</property> + </emphasis> and <emphasis> + <property moreinfo="none">Common</property> + </emphasis> that can be used to configure which directories should be automatically + refreshed and various general settings launchers, such as saving them in a project for + sharing the launcher within a team.</para> + + <para>On the <emphasis> + <property moreinfo="none">Main</property> + </emphasis> tab you see the following fields:</para> + + <table> + <title>Code generation "Main" tab fields</title> + + <tgroup cols="2"> + <colspec align="left" colnum="1" colwidth="1*"></colspec> + + <colspec colnum="2" colwidth="3*"></colspec> + + <colspec colnum="3" colwidth="0.5*"></colspec> + + <thead> + <row> + <entry align="center"> + <para>Field</para> + </entry> + + <entry align="center"> + <para>Description</para> + </entry> + </row> + </thead> + + <tbody> + <row> + <entry> + <para>Console Configuration</para> + </entry> + + <entry> + <para>The name of the console configuration which should be used when code + generating</para> + </entry> + </row> + + <row> + <entry> + <para>Output directory</para> + </entry> + + <entry> + <para>Path to a directory where all output will be written by default. Be aware that + existing files will be overwritten, so be sure to specify the correct + directory.</para> + </entry> + </row> + + <row> + <entry> + <para>Reverse engineer from JDBC Connection</para> + </entry> + + <entry> + <para>If enabled, the tools will reverse engineer the database available via the + connection information in the selected Hibernate Console Configuration and + generate code based on the database schema. If not enabled, the code generation + will just be based on the mappings already specified in the Hibernate Console + configuration.</para> + </entry> + </row> + + <row> + <entry> + <para>Package</para> + </entry> + + <entry> + <para>The package name here is used as the default package name for any entities + found when reverse engineering</para> + </entry> + </row> + + <row> + <entry> + <para>reveng.xml</para> + </entry> + + <entry> + <para>Path to a reveng.xml file. A reveng.xml file allows you to control certain + aspects of the reverse engineering. e.g. how jdbc types are mapped to hibernate + types and especially important which tables are included/excluded from the + process. Clicking "setup" allows you to select an existing reveng.xml file or + create a new one. See more details about the reveng.xml file in <xref linkend="reverseengineering"></xref>.</para> + </entry> + </row> + + <row> + <entry> + <para>reveng. strategy</para> + </entry> + + <entry> + <para>If reveng.xml does not provide enough customization you can provide your own + implementation of an ReverseEngineeringStrategy. The class needs to be in the + classpath of the Console Configuration, otherwise you will get class not found + exceptions. See <xref linkend="custom-reveng-strategy"></xref> for details and an + example of a custom strategy.</para> + </entry> + </row> + + <row> + <entry> + <para>Generate basic typed composite ids</para> + </entry> + + <entry> + <para>A table that has a multi-colum primary key a <composite-id> + mapping will always be created. If this option is enabled and there are matching + foreign-keys each key column is still considered a 'basic' scalar (string, long, + etc.) instead of a reference to an entity. If you disable this option a + <key-many-to-one> instead. Note: a <many-to-one> + property is still created, but is simply marked as non-updatable and + non-insertable.</para> + </entry> + </row> + + <row> + <entry> + <para>Detect optimistic lock columns</para> + </entry> + + <entry> + <para>Automatically detect optimistic lock columns. Controllable via reveng. + strategy; the current default is to use columns named VERSION or TIMESTAMP.</para> + </entry> + </row> + + <row> + <entry> + <para>Detect many-to-many tables</para> + </entry> + + <entry> + <para>Automatically detect many-to-many tables. Controllable via reveng. + strategy.</para> + </entry> + </row> + + <row> + <entry> + <para>Use custom templates</para> + </entry> + + <entry> + <para>If enabled, the Template directory will be searched first when looking up the + templates, allowing you to redefine how the individual templates process the + hibernate mapping model.</para> + </entry> + </row> + + <row> + <entry> + <para>Template directory</para> + </entry> + + <entry> + <para>A path to a directory with custom templates</para> + </entry> + </row> + </tbody> + </tgroup> + </table> + </section> + + <section> + <title>Exporters</title> + + <para>The <emphasis> + <property moreinfo="none">Exporters</property> + </emphasis> tab is used to specify which type of code that should be generated. Each + selection represents an Exporter that is responsible for generating the code, hence the + name.</para> + + <figure float="0"> + <title>Selecting Exporters</title> + <mediaobject> + <imageobject role="fo"> + <imagedata align="center" fileref="images/plugins/plugins_8.png" format="PNG" scale="80"></imagedata> + </imageobject> + + <imageobject role="html"> + <imagedata align="center" fileref="images/plugins/plugins_8.png" format="PNG"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>The following table describes in short the various exporters. Remember you can + add/remove any Exporters depending on your needs.</para> + + <table> + <title>Code generation "Exporter" tab fields</title> + + <tgroup cols="2"> + <colspec align="left" colnum="1" colwidth="1*"></colspec> + + <colspec colnum="2" colwidth="3*"></colspec> + + <thead> + <row> + <entry align="center"> + <para>Field</para> + </entry> + + <entry align="center"> + <para>Description</para> + </entry> + </row> + </thead> + + <tbody> + <row> + <entry> + <para>Domain code</para> + </entry> + + <entry> + <para>Generates POJO's for all the persistent classes and components found in the + given Hibernate configuration.</para> + </entry> + </row> + + <row> + <entry> + <para>DAO code</para> + </entry> + + <entry> + <para>Generates a set of DAO's for each entity found.</para> + </entry> + </row> + + <row> + <entry> + <para>Hibernate XML Mappings</para> + </entry> + + <entry> + <para>Generate mapping (hbm.xml) files for each entity.</para> + </entry> + </row> + + <row> + <entry> + <para>Hibernate XML Configuration</para> + </entry> + + <entry> + <para>Generate a hibernate.cfg.xml file. Used to keep the hibernate.cfg.xml update + with any new found mapping files.</para> + </entry> + </row> + + <row> + <entry> + <para>Schema Documentation (.html)</para> + </entry> + + <entry> + <para>Generates a set of html pages that documents the database schema and some of + the mappings.</para> + </entry> + </row> + + <row> + <entry> + <para>Generic Exporter (hbmtemplate)</para> + </entry> + + <entry> + <para>Fully customizable exporter which can be used to perform custom + generation.</para> + </entry> + </row> + + </tbody> + </tgroup> + </table> + + <para>Each Exporter listens to certain properties and these can be setup in the <emphasis> + <property moreinfo="none">Properties</property> + </emphasis> section where you can add/remove predefined or customer properties for each of + the exporters. The following table lists the time of writing predefined properties:</para> + + <para> + <table> + <title>Exporter Properties</title> + + <tgroup cols="2"> + <colspec align="left" colnum="1" colwidth="1*"></colspec> + + <colspec colnum="2" colwidth="3*"></colspec> + + <thead> + <row> + <entry align="center"> + <para>Name</para> + </entry> + + <entry align="center"> + <para>Description</para> + </entry> + </row> + </thead> + + <tbody> + <row> + <entry> + <para>jdk5</para> + </entry> + + <entry> + <para>Generate Java 5 syntax</para> + </entry> + </row> + + <row> + <entry> + <para>ejb3</para> + </entry> + + <entry> + <para>Generate EJB 3 annotations</para> + </entry> + </row> + + <row> + <entry> + <para>for_each</para> + </entry> + + <entry> + <para>Specifies for which type of model elements the exporter should create a file + and run through the templates. Possible values are: entity, component, + configuration</para> + </entry> + </row> + + <row> + <entry> + <para>template_path</para> + </entry> + + <entry> + <para>Custom template directory for this specific exporter. You can use Eclipse + variables.</para> + </entry> + </row> + + <row> + <entry> + <para>template_name</para> + </entry> + + <entry> + <para>Name for template relative to the template path</para> + </entry> + </row> + + <row> + <entry> + <para>outputdir</para> + </entry> + + <entry> + <para>Custom output directory for this specific exporter. You can use Eclipse + variables.</para> + </entry> + </row> + + <row> + <entry> + <para>file_pattern</para> + </entry> + + <entry> + <para>Pattern to use for the generated files, relatively for the output dir. + Example: {package-name}/{class-name}.java .</para> + </entry> + </row> + + + + <row> + <entry> + <para>dot.executable</para> + </entry> + + <entry> + <para>Executable to run GraphViz (only relevant, but optional for Schema + documentation)</para> + </entry> + </row> + </tbody> + </tgroup> + </table> + </para> + </section> + </section> + + <section id="map_config_editor"> + <title>Hibernate Mapping and Configuration File Editor</title> + + <para>The <property moreinfo="none">Hibernate Mapping File editor</property> provides XML editing functionality + for the <emphasis> + <property moreinfo="none">hbm.xml </property> + </emphasis> and <emphasis> + <property moreinfo="none">cfg.xml</property> + </emphasis> files. The editor is based on the Eclipse WTP tools and extends its functionality + to provide Hibernate specific code completion.</para> + + <figure float="0"> + <title>XML Editing Functionality</title> + <mediaobject> + <imageobject role="fo"> + <imagedata align="center" fileref="images/plugins/plugins_9.png" format="PNG" scale="80"></imagedata> + </imageobject> + + <imageobject role="html"> + <imagedata align="center" fileref="images/plugins/plugins_9.png" format="PNG"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <section> + <title>Java property/class completion</title> + + <para>Package, class, and field completion is enabled for relevant XML attributes. The + auto-completion detects its context and limits the completion for e.g. <emphasis> + <property moreinfo="none"><property></property> + </emphasis> and only shows the properties/fields available in the enclosing <emphasis> + <property moreinfo="none"><class></property> + </emphasis>, <emphasis> + <property moreinfo="none"><subclass></property> + </emphasis> etc. It is also possible to navigate from the <emphasis> + <property moreinfo="none">hbm.xml</property> + </emphasis> files to the relevant class/field in java code.</para> + + <figure float="0"> + <title>Navigation Functionality</title> + + <mediaobject> + <imageobject role="fo"> + <imagedata align="center" fileref="images/plugins/plugins_10.png" format="PNG" scale="80"></imagedata> + </imageobject> + + <imageobject role="html"> + <imagedata align="center" fileref="images/plugins/plugins_10.png" format="PNG"></imagedata> + </imageobject> + </mediaobject> + + </figure> + + <para>This is done via the standard hyperlink navigation functionality in Eclipse; per default + it is done by pressing F3 while the cursor is on a class/field or by pressing <emphasis> + <property moreinfo="none">Ctrl</property> + </emphasis> and the mouse button to perform the same navigation.</para> + + <para>For java completion and navigation to work the file needs to reside inside an Eclipse + Java project, otherwise no completion will occur.</para> + <note> + <title>Note:</title> + <para>Java completion does not require a Hibernate console configuration to be used.</para> + </note> + </section> + + <section> + <title>Table/Column completion</title> + + <para>Table and column completion is also available for all table and column attributes. </para> + + <figure float="0"> + <title>Table and Column Completion</title> + <mediaobject> + <imageobject role="fo"> + <imagedata align="center" fileref="images/plugins/plugins_11.png" format="PNG" scale="80"></imagedata> + </imageobject> + + <imageobject role="html"> + <imagedata align="center" fileref="images/plugins/plugins_11.png" format="PNG"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <important> + <title>Important:</title> + <para>Table/Column completion requires a proper configured hibernate console configuration + and this configuration should be the default for the project where the <emphasis> + <property moreinfo="none">hbm.xml</property> + </emphasis> resides.</para> + </important> + + <para>You can check which console configuration is selected under the Properties of a project + and look under the <emphasis> + <property moreinfo="none">Hibernate Settings</property> + </emphasis> page. When a proper configuration is selected it will be used to fetch the + table/column names in the background.</para> + + <note> + <title>Note:</title> + <para>Currently it is not recommended to use this feature on large databases since it does + not fetch the information iteratively. It will be improved in future versions.</para> + </note> + </section> + + <section> + <title>Configuration property completion</title> + + <para>In <emphasis> + <property moreinfo="none">cfg.xml</property> + </emphasis> code completion for the value of <emphasis> + <property moreinfo="none"><property> name</property> + </emphasis> attributes is available.</para> + + + <figure float="0"> + <title>Property Completion</title> + <mediaobject> + <imageobject role="fo"> + <imagedata align="center" fileref="images/plugins/plugins_12.png" format="PNG" scale="80"></imagedata> + </imageobject> + + <imageobject role="html"> + <imagedata align="center" fileref="images/plugins/plugins_12.png" format="PNG"></imagedata> + </imageobject> + </mediaobject> + </figure> + + </section> + </section> + + <section id="map_config_struct_editor"> + <title>Structured Hibernate Mapping and Configuration File Editor</title> + <para>The structured editor represents the file in the tree form. It also allows to modify the + structure of the file and its elements with the help of tables provided on the right-hand + area.</para> + + <para>To open any mapping file in the editor, choose <emphasis> + <property moreinfo="none">Open With > Hibernate 3.0 XML Editor</property> + </emphasis> option from the context menu of the file. The editor should look as follows:</para> + + <figure float="0"> + <title>Structured hbm.xml Editor</title> + + <mediaobject> + <imageobject> + <imagedata fileref="images/plugins/plugins_12_a.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>For the configuration file you should choose <emphasis> + <property moreinfo="none">Open With > Hibernate Configuration 3.0 XML Editor</property> + </emphasis>option.</para> + + <figure float="0"> + <title>Structured cfg.xml Editor</title> + + <mediaobject> + <imageobject> + <imagedata fileref="images/plugins/plugins_12_b.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + </section> + + <section id="rev_xml_editor"> + <title>Reveng.xml Editor</title> + + <para>A <emphasis> + <property moreinfo="none">reveng.xml </property> + </emphasis> file is used to customize and control how reverse engineering is performed by the + tools. The plugins provide an editor to ease the editing of this file and hence used to + configure the reverse engineering process.</para> + + <para>The editor is intended to allow easy definition of type mappings, table include/excludes + and specific override settings for columns, e.g. define an explicit name for a column when the + default naming rules are not applicable.</para> + + <note> + <title>Note:</title> + <para> Not all the features of the <emphasis> + <property moreinfo="none">.reveng.xml </property> + </emphasis> file are exposed or fully implemented in the editor, but the main functionality + is there. To understand the full flexibility of the <emphasis> + <property moreinfo="none">reveng.xml</property> + </emphasis>, please see <xref linkend="hibernaterevengxmlfile"></xref> + </para> + </note> + + <para>The editor is activated as soon as an <emphasis> + <property moreinfo="none">.reveng.xml </property> + </emphasis> file is opened. To get an initial <emphasis> + <property moreinfo="none">reveng.xml </property> + </emphasis> file the <property moreinfo="none">Reverse Engineering File Wizard</property> can be started via <emphasis> + <property moreinfo="none">Ctrl+N</property> + </emphasis> and <emphasis> + <property moreinfo="none">Hibernate > Hibernate Reverse Engineering File (reveng.xml)</property> + </emphasis> then.</para> + + <figure float="0"> + <title>Overview Page</title> + <mediaobject> + <imageobject role="fo"> + <imagedata align="center" fileref="images/plugins/plugins_22.png" format="PNG" scale="80"></imagedata> + </imageobject> + + <imageobject role="html"> + <imagedata align="center" fileref="images/plugins/plugins_22.png" format="PNG"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>Or you can get it via the <property moreinfo="none">Code Generation Launcher</property> by checking the + proper section in the <emphasis> + <property moreinfo="none">Main</property> + </emphasis> tab of the <link linkend="hib_code_gen">Hibernate Code Generation Wizard</link>.</para> + + <para>The following screenshot shows the <emphasis> + <property moreinfo="none">Overview</property> + </emphasis> page where the wanted console configuration is selected (auto-detected if + Hibernate 3 support is enabled for the project)</para> + + <figure float="0"> + <title>Overview Page</title> + <mediaobject> + <imageobject role="fo"> + <imagedata align="center" fileref="images/plugins/plugins_13.png" format="PNG" scale="80"></imagedata> + </imageobject> + + <imageobject role="html"> + <imagedata align="center" fileref="images/plugins/plugins_13.png" format="PNG"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>The <emphasis> + <property moreinfo="none">Table Filter</property> + </emphasis> page allows you to specify which tables to include and exclude. Pressing <emphasis> + <property moreinfo="none">Refresh</property> + </emphasis> shows the tables from the database that have not yet been excluded.</para> + + <figure float="0"> + <title>Table Filters Page</title> + <mediaobject> + <imageobject role="fo"> + <imagedata align="center" fileref="images/plugins/plugins_14.png" format="PNG" scale="80"></imagedata> + </imageobject> + + <imageobject role="html"> + <imagedata align="center" fileref="images/plugins/plugins_14.png" format="PNG"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>The <emphasis> + <property moreinfo="none">Type Mappings</property> + </emphasis> page is used for specifying type mappings from JBDC types to any Hibernate type + (including usertypes) if the default rules are not applicable. Here again to see the database + tables press <emphasis> + <property moreinfo="none">Refresh</property> + </emphasis> button underneath. More about type mappings you can find further in the <link linkend="type_map">Type Mappings</link> section.</para> + + <figure float="0"> + <title>Type Mappings Page</title> + <mediaobject> + <imageobject role="fo"> + <imagedata align="center" fileref="images/plugins/plugins_15.png" format="PNG" scale="80"></imagedata> + </imageobject> + + <imageobject role="html"> + <imagedata align="center" fileref="images/plugins/plugins_15.png" format="PNG"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>The <emphasis> + <property moreinfo="none">Table and Columns</property> + </emphasis> page allows you to explicit set e.g. which hibernatetype and propertyname that + should be used in the reverse engineered model. For more details on how to configure the + tables while reverse engineering read the <link linkend="tab_and_col">Specific table + configuration</link> section.</para> + + <figure float="0"> + <title>Table and Columns Page</title> + <mediaobject> + <imageobject role="fo"> + <imagedata align="center" fileref="images/plugins/plugins_16.png" format="PNG" scale="80"></imagedata> + </imageobject> + + <imageobject role="html"> + <imagedata align="center" fileref="images/plugins/plugins_16.png" format="PNG"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>Now that you have configured all necessary parts, you can learn how to work with + <property moreinfo="none">Hibernate Console Perspective</property>.</para> + </section> + + <section id="hib_console"> + <title>Hibernate Console Perspective</title> + + <para>The <property moreinfo="none">Hibernate Console Perspective</property> combines a set of views which allow + you to see the structure of your mapped entities/classes, edit HQL queries, execute the + queries, and see the results. To use this perspective you need to create a <link linkend="console_conf">Console configuration</link>.</para> + + <section> + <title>Viewing the entity structure</title> + + <para>To view your new configuration and entity/class structure, switch to <property moreinfo="none">Hibernate + Configurations View</property>. Expanding the tree allows you to browse the class/entity + structure and see the relationships.</para> + + <figure float="0"> + <title>Hibernate Console Perspective</title> + <mediaobject> + <imageobject role="fo"> + <imagedata align="center" fileref="images/plugins/plugins_17.png" scale="80"></imagedata> + </imageobject> + + <imageobject role="html"> + <imagedata align="center" fileref="images/plugins/plugins_17.png"></imagedata> + </imageobject> + </mediaobject> + + </figure> + + <para>The <property moreinfo="none">Console Configuration</property> does not dynamically adjust to changes + done in mappings and java code. To reload the configuration select the configuration and + click the <emphasis> + <property moreinfo="none">Reload</property> + </emphasis> button in the view toolbar or in the context menu.</para> + + <para>Besides, it's possible to open source and mapping files for objects showed in + <property moreinfo="none">Hibernate Configurations View</property>. Just bring up the context menu for a + necessary object and select <emphasis> + <property moreinfo="none">Open Source File</property> + </emphasis> to see appropriate Java class or <emphasis> + <property moreinfo="none">Open Mapping File</property> + </emphasis> to open a proper <emphasis> + <property moreinfo="none">.hbm.xml</property>.</emphasis></para> + + <figure float="0"> + <title>Opening Source for Objects</title> + + <mediaobject> + <imageobject> + <imagedata fileref="images/plugins/plugins_17_a.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <section id="map_diagram"> + <title>Mapping Diagram</title> + + <para>In order to get a visual feel on how entities are related as well as view their + structures, a <property moreinfo="none">Mapping Diagram</property> is provided. It is available by right + clicking on the entity you want a mapping diagram for and then choosing <emphasis> + <property moreinfo="none">Open Mapping Diagram</property>.</emphasis></para> + + <figure float="0"> + <title>Mapping Diagram</title> + <mediaobject> + <imageobject role="fo"> + <imagedata align="center" fileref="images/plugins/plugins_18.png" scale="80"></imagedata> + </imageobject> + + <imageobject role="html"> + <imagedata align="center" fileref="images/plugins/plugins_18.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>For better navigating on the Diagram use <property moreinfo="none">Outline view</property> which is + available in the structural and graphical modes.</para> + <figure float="0"> + <title>Navigating in the Structural Mode</title> + + <mediaobject> + <imageobject> + <imagedata fileref="images/plugins/plugins_18_a.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>To switch over between the modes use the buttons in the top-right corner of the + <property moreinfo="none">Outline view</property>.</para> + + <figure float="0"> + <title>Navigating in the Graphical Mode</title> + + <mediaobject> + <imageobject> + <imagedata fileref="images/plugins/plugins_18_b.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>As in <property moreinfo="none">Hibernate Configurations View</property> in <property moreinfo="none">Mapping + Diagram</property> it's also possible to open source/mapping file for a chosen + object by selecting appropriate option in the context menu. </para> + + <figure float="0"> + <title>Navigating on the Diagram</title> + + <mediaobject> + <imageobject> + <imagedata fileref="images/plugins/plugins_18_c.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>If you ask to open source/mapping file by right clicking on any entity element, this + element will be highlighted in the open file.</para> + + <figure float="0"> + <title>Opening Source for Object</title> + + <mediaobject> + <imageobject> + <imagedata fileref="images/plugins/plugins_18_d.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>Finally, if you need to have your Diagram exported as <emphasis><property moreinfo="none">.png + </property>,</emphasis> + <emphasis> + <property moreinfo="none">.jpeg</property> + </emphasis> or <emphasis><property moreinfo="none">.bmp </property>,</emphasis> you should right-click + anywhere in the <property moreinfo="none">Mapping Diagram editor</property> and select <emphasis> + <property moreinfo="none">Export as Image</property> + </emphasis>.</para> + + <figure float="0"> + <title>Mapping Diagram Export</title> + + <mediaobject> + <imageobject> + <imagedata fileref="images/plugins/plugins_18_e.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>As you can see on the figure above, <emphasis><property moreinfo="none">Undo</property>, </emphasis> + <emphasis> + <property moreinfo="none">Redo</property> + </emphasis> and <emphasis> + <property moreinfo="none">Auto layout </property> + </emphasis> options are also available through the context menu.</para> + </section> + </section> + + <section> + <title>Prototyping Queries</title> + + <para>Queries can be prototyped by entering them in the <property moreinfo="none">HQL</property> or + <property moreinfo="none">Criteria Editor</property>. The query editors are opened by right-clicking the + <property moreinfo="none">Console Configuration</property> and selecting either <property moreinfo="none">HQL + Editor</property> or <property moreinfo="none">Hibernate Criteria Editor</property>. The editors + automatically detect the chosen configuration.</para> + + <para>If the menu item is disabled then you need at first to create a <property moreinfo="none">Session + Factory</property>. That is done by simply expanding the <property moreinfo="none">Session + Factory</property> node.</para> + + <para>By brining up the context menu for a chosen entity or property in the <property moreinfo="none">Console + Configuration</property> and opening <emphasis> + <property moreinfo="none">HQL Editor</property> + </emphasis> or <emphasis> + <property moreinfo="none">Hibernate Criteria Editor</property> + </emphasis> you'll get a prefill query.</para> + + <figure float="0"> + <title>Entering Simple Queries</title> + <mediaobject> + <imageobject role="fo"> + <imagedata align="center" fileref="images/plugins/plugins_19.png" format="PNG" scale="80"></imagedata> + </imageobject> + + <imageobject role="html"> + <imagedata align="center" fileref="images/plugins/plugins_19.png" format="PNG"></imagedata> + </imageobject> + </mediaobject> + </figure> + <para>To copy a portion of code from .java file into a HQL or Criteria editor, make use of the + Quick Fix option (Ctrl + 1).</para> + + <figure float="0"> + <title>Quick Fix Option Demonstration</title> + + <mediaobject> + <imageobject> + <imagedata fileref="images/plugins/plugins_19_b.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + <para>You can also update the original java code according to changes in the HQL or Criteria + editor. For that you should save your HQL/Criteria query and submit the replacing in + appeared confirmation dialog.</para> + + <figure float="0"> + <title>Updating Java Code</title> + + <mediaobject> + <imageobject> + <imagedata fileref="images/plugins/plugins_19_c.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>Executing the query is done by clicking the green run button in the toolbar or pressing <emphasis> + <property moreinfo="none">Ctrl+Enter</property> + </emphasis>.</para> + + <para>Errors during creation of the <property moreinfo="none">Session Factory</property> or running the + queries (e.g. if your configuration or query is incorrect) will be shown in a message dialog + or inclined in the view that detected the error, you may get more information about the + error in the <property moreinfo="none">Error Log View</property> on the right pane.</para> + + <para>Results of a query will be shown in the <property moreinfo="none">Hibernate Query Result View</property> + and details of possible errors (syntax errors, database errors, etc.) can be seen in the + <property moreinfo="none">Error Log View</property>.</para> + + + <note> + <title>Note:</title> + <para>HQL queries are executed by default using <literal moreinfo="none">list()</literal> thus without any + limit of the size of the output the query could return a large result set. You might run + out of memory. To avoid this you can put a value in the Max results field to reduce the + number of elements returned.</para> + </note> + + <section> + <title>Dynamic Query Translator</title> + + <para>If the <property moreinfo="none">Hibernate Dynamic Query Translator View</property> is visible while + writing in the <property moreinfo="none">HQL Editor</property> it will show the generated SQL for a HQL + query.</para> + + <figure float="0"> + <title>Hibernate Dynamic Query Translator View</title> + <mediaobject> + <imageobject role="fo"> + <imagedata align="center" fileref="images/plugins/plugins_20.png" format="PNG" scale="80"></imagedata> + </imageobject> + + <imageobject role="html"> + <imagedata align="center" fileref="images/plugins/plugins_20.png" format="PNG"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>The translation is done each time you stop typing into the editor, if there are errors + in the HQL the parse exception will be shown embedded in the view.</para> + </section> + </section> + + <section> + <title>Properties View</title> + + <para>As you can see on the figure, <property moreinfo="none">Properties view</property> shows the number of + query results as well as the time of executing.</para> + + <figure float="0"> + <title>Properties View</title> + <mediaobject> + <imageobject role="fo"> + <imagedata align="center" fileref="images/plugins/plugins_21_a.png" format="PNG" scale="80"></imagedata> + </imageobject> + + <imageobject role="html"> + <imagedata align="center" fileref="images/plugins/plugins_21_a.png" format="PNG"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>It also displays the structure of any persistent object selected in the + <property moreinfo="none">Hibernate Query Results View</property>. Editing is not yet supported.</para> + + <figure float="0"> + <title>Properties View for Selected Object</title> + <mediaobject> + <imageobject role="fo"> + <imagedata align="center" fileref="images/plugins/plugins_21_b.png" format="PNG" scale="80"></imagedata> + </imageobject> + + <imageobject role="html"> + <imagedata align="center" fileref="images/plugins/plugins_21_b.png" format="PNG"></imagedata> + </imageobject> + </mediaobject> + </figure> + </section> + </section> + + <section id="debug_log"> + <title>Enable debug logging in the plugins</title> + + <para>It is possible to configure the eclipse plugin to route all logging made by the plugins + and hibernate code it self to the <property moreinfo="none">Error Log View</property> in Eclipse.</para> + + <para>This is done by editing the <emphasis> + <property moreinfo="none">hibernate-log4j.properties</property> + </emphasis> in <emphasis> + <property moreinfo="none">org.hibernate.eclipse/ directory/jar</property> + </emphasis>. This file includes a default configuration that only logs WARN and above to a set + of custom appenders (PluginFileAppender and PluginLogAppender). You can change these settings + to be as verbose or silent as you please - see <ulink url="http://www.hibernate.org/5.html">Hibernate Documentation</ulink> for interesting categories and Log4j documentation.</para> + + <section> + <title>Relevant Resources Links</title> + <para>Find more on how to configure logging via a log4j property file in <ulink url="http://supportweb.cs.bham.ac.uk/docs/tutorials/docsystem/build/tutorials/...">Log4j documentation</ulink>.</para> + </section> + </section> + + <section id="dali_integration"> + <title>Hibernate support for Dali plugins in Eclipse WTP</title> + + <para>Starting from 3.0.0 Alpha1 version of <property moreinfo="none">JBoss Tools</property> Hibernate plugins + support Eclipse Dali integration what now makes it possible to use a Hibernate as a complete + JPA development platform.</para> + + <para>When starting your new JPA project from <emphasis> + <property moreinfo="none">New > Other... > JPA > JPA Project</property> + </emphasis> (or simply <emphasis> + <property moreinfo="none">New > JPA Project</property> + </emphasis> in <property moreinfo="none">JPA Perspective</property>) on the JPA Facet page you'll be + prompted to choose Hibernate as a target platform.</para> + + <figure float="0"> + <title>Targeting at Hibernate Platform</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/plugins/plugins_23.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>By enabling Hibernate platform specific features you can now generate DDL and Entities. + For that find <emphasis> + <property moreinfo="none">JPA Tools > Generate DDL.../Generate Entities...</property> + </emphasis> options in the context menu of your JPA project.</para> + + <figure float="0"> + <title>Generate DDL/Entities</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/plugins/plugins_24.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>The Generate DDL/Entities wizards first will ask you to choose the <property moreinfo="none">Console + Configuration</property>.</para> + + <figure float="0"> + <title>Generate Entities Wizard</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/plugins/plugins_25.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <note> + <title>Note:</title> + + <para>Please note, currently the wizards require that you have a <link linkend="console_conf">Hibernate Console Configuration</link> already configured.</para> + </note> + </section> +</chapter> + + +<chapter id="ant" xml:base="file:///home/ochikvina/WORK/for_compare/trunk/hibernatetools/docs/reference/en/modules/ant.xml"> + <title>Ant Tools</title> + + <para>Maybe somebody will find it more preferable to use Ant for generation purposes. Thus, this + chapter is intended to get you ready to start using Hibernate Tools via Ant tasks.</para> + + <section> + <title>Introduction</title> + + <para>The <emphasis> + <property moreinfo="none">hibernate-tools.jar</property> + </emphasis> contains the core for the <property moreinfo="none">Hibernate Tools</property>. It is used as the + basis for both the Ant tasks described in this document and the eclipse plugins both available + from tools.hibernate.org. The <emphasis> + <property moreinfo="none">hibernate-tools.jar</property> + </emphasis> is located in your eclipse plugins directory at <emphasis> + <property moreinfo="none">/plugins/org.hibernate.eclipse.x.x.x/lib/tools/hibernate-tools.jar</property>.</emphasis></para> + <para>This jar is 100% independent from the eclipse platform and can thus be used independently + of eclipse.</para> + + <note> + <title>Note:</title> + <para>There might be incompatibilities with respect to the Hibernate3.jar bundled with the + tools and your own jar. Thus to avoid any confusion it is recommended to use the + hibernate3.jar and hibernate-annotations.jar bundled with the tools when you want to use the + Ant tasks. Do not worry about using e.g. Hibernate 3.2 jar's with e.g. a Hibernate 3.1 + project since the output generated will work with previous Hibernate 3 versions. </para> + </note> + </section> + + <section> + <title>The <hibernatetool> Ant Task</title> + + <para>To use the ant tasks you need to have the <emphasis> + <property moreinfo="none">hibernatetool</property> + </emphasis> task defined. That is done in your <emphasis> + <property moreinfo="none">build.xml</property> + </emphasis> by inserting the following xml (assuming the jars are in the + <literal moreinfo="none">lib</literal> directory): </para> + + <programlisting format="linespecific" role="XML"><![CDATA[<path id="toolslib"> + <path location="lib/hibernate-tools.jar" /> + <path location="lib/hibernate3.jar" /> + <path location="lib/freemarker.jar" /> + <path location="${jdbc.driver.jar}" /> +</path> + +<taskdef name="hibernatetool" + classname="org.hibernate.tool.ant.HibernateToolTask" + classpathref="toolslib" /> +]]></programlisting> + + <para>This <emphasis> + <property moreinfo="none"> + <literal moreinfo="none"><taskdef></literal> + </property> + </emphasis> defines an Ant task called <emphasis> + <property moreinfo="none"> hibernatetool </property> + </emphasis> which now can be used anywhere in your ant <emphasis> + <property moreinfo="none">build.xml</property> + </emphasis> files. It is important to include all the <property moreinfo="none">Hibernate Tools</property> + dependencies as well as the jdbc driver.</para> + + <para>Notice that to use the annotation based Configuration you must <ulink url="http://annotations.hibernate.org">get a release</ulink>. </para> + + <para></para> + + <para>When using the <emphasis> + <property moreinfo="none"> hibernatetool </property> + </emphasis> task you have to specify one or more of the following:</para> + + <programlisting format="linespecific" role="XML"><![CDATA[<hibernatetool + destdir="defaultDestinationDirectory" + templatepath="defaultTemplatePath" +> + <classpath ...> + <property key="propertyName" value="value"/> + <propertyset ...> + (<configuration ...>|<annotationconfiguration ...>| + <jpaconfiguration ...>|<jdbcconfiguration ...>) + (<hbm2java>,<hbm2cfgxml>,<hbmtemplate>,...) +</hibernatetool>]]></programlisting> + + <table frame="topbot"> + <title>Hibernatetool attributes</title> + + <tgroup cols="3"> + + <colspec colwidth="0.3*"></colspec> + + <colspec colwidth="1.0*"></colspec> + + <colspec colwidth="0.3*"></colspec> + + + <thead> + <row> + <entry>Attribute name</entry> + + <entry>Definition</entry> + + <entry>Attribute use</entry> + </row> + </thead> + + <tbody> + <row> + <entry> + <para>destdir</para> + </entry> + + <entry> + <para>Destination directory for files generated with exporters</para> + </entry> + + <entry> + <para>Required</para> + </entry> + </row> + + <row> + <entry> + <para>templatepath</para> + </entry> + + <entry> + <para>A path to be used to look up user-edited templates</para> + </entry> + + <entry> + <para>Optional</para> + </entry> + </row> + + <row> + <entry> + <para>classpath</para> + </entry> + + <entry> + <para>A classpath to be used to resolve resources, such as mappings and + usertypes</para> + </entry> + + <entry> + <para>Optional, but very often required</para> + </entry> + </row> + + + <row> + <entry> + <para>property (and propertyset)</para> + </entry> + + <entry> + <para>Used to set properties to control the exporters. Mostly relevant for providing + custom properties to user defined templates</para> + </entry> + + <entry> + <para>Optional</para> + </entry> + </row> + + <row> + <entry> + <para>configuration (annotationconfiguration, jpaconfiguration, + jdbcconfiguration)</para> + </entry> + + <entry> + <para>One of four different ways of configuring the Hibernate Meta Model must be + specified</para> + </entry> + + <entry> + <para></para> + </entry> + </row> + + <row> + <entry> + <para>hbm2java (hbm2cfgxml, hbmtemplate, etc.)</para> + </entry> + + <entry> + <para>One or more of the exporters must be specified</para> + </entry> + + <entry> + <para></para> + </entry> + </row> + + </tbody> + + </tgroup> + </table> + + <section> + <title>Basic examples</title> + + <para>The following example shows the most basic setup for generating pojo's via <emphasis> + <property moreinfo="none"><hbm2java></property> + </emphasis> from a normal <emphasis> + <property moreinfo="none"> + <literal moreinfo="none">hibernate.cfg.xml</literal> + </property>. </emphasis> The output will be put in the <emphasis> + <property moreinfo="none">${build.dir}/generated</property> + </emphasis> directory.</para> + + <programlisting format="linespecific" role="XML"><![CDATA[<hibernatetool destdir="${build.dir}/generated"> + <classpath> + <path location="${build.dir}/classes"/> + </classpath> + + <configuration configurationfile="hibernate.cfg.xml"/> + <hbm2java/> +</hibernatetool>]]></programlisting> + + + <para>The following example is similar, but now we are performing multiple exports from the + same configuration. We are exporting the schema via <emphasis> + <property moreinfo="none"><hbm2dll></property>, </emphasis> generates some DAO code via <emphasis> + <property moreinfo="none"><hbm2dao></property> + </emphasis> and finally runs a custom code generation via <emphasis> + <property moreinfo="none"><hbmtemplate></property>. </emphasis> This is again from a normal <emphasis> + <property moreinfo="none">hibernate.cfg.xml</property> + </emphasis> and the output is still put in the <emphasis> + <property moreinfo="none"> + <literal moreinfo="none">${build.dir}/generated</literal> + </property> + </emphasis> directory. Furthermore the example also shows where a classpath is specified + when you e.g. have custom usertypes or some mappings that is needed to be looked up as a + classpath resource.</para> + + <programlisting format="linespecific" role="XML"><![CDATA[<hibernatetool destdir="${build.dir}/generated"> + <classpath> + <path location="${build.dir}/classes"/> + </classpath> + + <configuration configurationfile="hibernate.cfg.xml"/> + <hbm2ddl/> + <hbm2dao/> + <hbmtemplate + filepattern="{package-name}/I{class-name}Constants.java" + templatepath="${etc.dir}/customtemplates" + template="myconstants.vm" + /> +</hibernatetool>]]></programlisting> + + </section> + </section> + + <section> + <title>Hibernate Configurations</title> + + <para><literal moreinfo="none">Hibernatetool</literal> supports four different Hibernate configurations: A + standard Hibernate configuration <emphasis> + (<property moreinfo="none"><configuration></property>), </emphasis> Annotation based + configuration <emphasis> (<property moreinfo="none"><annotationconfiguration></property>), + </emphasis> JPA persistence based configuration <emphasis> + (<property moreinfo="none"><jpaconfiguration></property>) </emphasis> and a JDBC based + configuration <emphasis> (<property moreinfo="none"><jdbcconfiguration></property>) </emphasis> + for use when reverse engineering.</para> + + <para>Each have in common that they are able to build up a Hibernate Configuration object from + which a set of exporters can be run to generate various output. </para> + + <note> + <title>Note:</title> + <para>Output can be anything, e.g. specific files, statements execution against a database, + error reporting or anything else that can be done in java code.</para> + </note> + + <para>The following sections describe what the various configurations can do, plus lists the + individual settings they have.</para> + + <section> + <title>Standard Hibernate Configuration (<configuration>)</title> + + <para>A <emphasis> + <property moreinfo="none"><configuration></property> + </emphasis> is used to define a standard Hibernate configuration. A standard Hibernate + configuration reads the mappings from a <emphasis> + <property moreinfo="none">cfg.xml</property> + </emphasis> and/or a fileset.</para> + + <programlisting format="linespecific" role="XML"><![CDATA[<configuration + configurationfile="hibernate.cfg.xml" + propertyfile="hibernate.properties" + entityresolver="EntityResolver classname" + namingstrategy="NamingStrategy classname" +> + <fileset...> + + </configuration>]]></programlisting> + + <table frame="topbot"> + <title>Configuration attributes</title> + + <tgroup cols="3"> + + <colspec colwidth="0.3*"></colspec> + + <colspec colwidth="1.0*"></colspec> + + <colspec colwidth="0.3*"></colspec> + + + <thead> + <row> + <entry>Attribute name</entry> + + <entry>Definition</entry> + + <entry>Attribute use</entry> + </row> + </thead> + + <tbody> + <row> + <entry> + <para>configurationfile</para> + </entry> + + <entry> + <para>The name of a Hibernate configuration file, e.g. "hibernate.cfg.xml"</para> + </entry> + + <entry> + <para>Optional</para> + </entry> + </row> + + <row> + <entry> + <para>propertyfile</para> + </entry> + + <entry> + <para>The name of a property file, e.g. "hibernate.properties"</para> + </entry> + + <entry> + <para>Optional</para> + </entry> + </row> + + <row> + <entry> + <para>entity-resolver</para> + </entry> + + <entry> + <para>Name of a class that implements org.xml.sax.EntityResolver. Used if the + mapping files require custom entity resolver</para> + </entry> + + <entry> + <para>Optional</para> + </entry> + </row> + + + <row> + <entry> + <para>namingstrategy</para> + </entry> + + <entry> + <para>Name of a class that implements org.hibernate.cfg.NamingStrategy. Used for + setting up the naming strategy in Hibernate which controls the automatic naming of + tables and columns.</para> + </entry> + + <entry> + <para>Optional</para> + </entry> + </row> + + <row> + <entry> + <para>fileset</para> + </entry> + + <entry> + <para>A standard Ant fileset. Used to include hibernate mapping files. Remember that + if mappings are already specified in the hibernate.cfg.xml then it should not be + included via the fileset as it will result in duplicate import exceptions.</para> + </entry> + + <entry> + <para></para> + </entry> + </row> + + </tbody> + + </tgroup> + </table> + + <section> + <title>Example</title> + + <para>This example shows an example where no <emphasis> + <property moreinfo="none"> + <literal moreinfo="none">hibernate.cfg.xml</literal> + </property> + </emphasis> exists, and a <emphasis> + <property moreinfo="none"> hibernate.properties </property> + </emphasis> and fileset is used instead. </para> + + <note> + <title>Note:</title> + <para> Hibernate will still read any global <emphasis> + <property moreinfo="none">hibernate.properties</property> + </emphasis> available in the classpath, but the specified properties file here will + override those values for any non-global property.</para> + </note> + + <programlisting format="linespecific" role="XML"><![CDATA[<hibernatetool destdir="${build.dir}/generated"> + <configuration propertyfile="{etc.dir}/hibernate.properties"> + <fileset dir="${src.dir}"> + <include name="**/*.hbm.xml"/> + <exclude name="**/*Test.hbm.xml"/> + </fileset> + </configuration> + +  + +</hibernatetool>]]></programlisting> + + </section> + </section> + + <section> + <title>Annotation based Configuration (<annotationconfiguration>)</title> + + <para>An <emphasis> + <property moreinfo="none"><annotationconfiguration></property> + </emphasis> is used when you want to read the metamodel from EJB3/Hibernate Annotations + based POJO's.</para> + + <important> + <title>Important:</title> + <para>To use it remember to put the jar files needed for using hibernate annotations in the + classpath of the <emphasis> + <property moreinfo="none"><taskdef></property>, </emphasis> i. e. + hibernate-annotations.jar and hibernate-commons-annotations.jar.</para> + </important> + + <para>The <emphasis> + <property moreinfo="none"><annotationconfiguration></property> + </emphasis> supports the same attributes as a <emphasis> + <property moreinfo="none"><configuration></property> + </emphasis> except that the configurationfile attribute is now required as that is from + where an <literal moreinfo="none">AnnotationConfiguration</literal> gets the list of classes/packages it + should load.</para> + + <para>Thus the minimal usage is:</para> + + <programlisting format="linespecific" role="XML"><![CDATA[<hibernatetool destdir="${build.dir}/generated"> + <annotationconfiguration + configurationfile="hibernate.cfg.xml"/> + +  + +</hibernatetool> +]]></programlisting> + + </section> + + <section> + <title>JPA based configuration (<jpaconfiguration>)</title> + + <para>A <emphasis> + <property moreinfo="none"><jpaconfiguration></property> + </emphasis> is used when you want to read the metamodel from JPA/Hibernate Annotation where + you want to use the auto-scan configuration as defined in the JPA spec (part of EJB3). In + other words, when you do not have a <emphasis> + <property moreinfo="none">hibernate.cfg.xml</property>, </emphasis> but instead have a setup where you use + a <emphasis> + <property moreinfo="none">persistence.xml</property> + </emphasis> packaged in a JPA compliant manner.</para> + + <para>The <emphasis> + <property moreinfo="none"><jpaconfiguration></property> + </emphasis> will simply just try and auto-configure it self based on the available + classpath, e.g. look for <emphasis> + <property moreinfo="none">META-INF/persistence.xml</property>. </emphasis></para> + + <para>The <emphasis> + <property moreinfo="none">persistenceunit</property> + </emphasis> attribute can be used to select a specific persistence unit. If no <emphasis> + <property moreinfo="none">persistenceunit</property> + </emphasis> is specified it will automatically search for one and if a unique one is found, + use it, but if multiple persistence units are available it will error.</para> + + <para>To use a <emphasis> + <property moreinfo="none"><jpaconfiguration></property> + </emphasis> you will need to specify some additional jars from Hibernate EntityManager in + the <emphasis> + <property moreinfo="none"><taskdef></property> + </emphasis> of the hibernatetool. The following shows a full setup:</para> + + <programlisting format="linespecific" role="XML"><![CDATA[<path id="ejb3toolslib"> + <path refid="jpatoolslib"/>  + <path location="lib/hibernate-annotations.jar" /> + <path location="lib/ejb3-persistence.jar" /> + <path location="lib/hibernate-entitymanager.jar" /> + <path location="lib/jboss-archive-browsing.jar" /> + <path location="lib/javaassist.jar" /> +</path> + +<taskdef name="hibernatetool" + classname="org.hibernate.tool.ant.HibernateToolTask" + classpathref="jpatoolslib" /> + +<hibernatetool destdir="${build.dir}"> + <jpaconfiguration persistenceunit="caveatemptor"/> + <classpath> +  + <path location="${build.dir}/jpa/classes" /> + </classpath> + +  + +</hibernatetool> +]]></programlisting> + + + <note> + <title>Note:</title> + <para>ejb3configuration was the name used in previous versions. It still works but will emit + a warning telling you to use <literal moreinfo="none">jpaconfiguration</literal> instead.</para> + </note> + + </section> + + <section> + <title>JDBC Configuration for reverse engineering (<jdbcconfiguration>)</title> + + <para>A <emphasis> + <property moreinfo="none"> + <literal moreinfo="none"><jdbcconfiguration></literal> + </property> + </emphasis> is used to perform reverse engineering of the database from a JDBC connection.</para> + + <para>This configuration works by reading the connection properties either from <emphasis> + <property moreinfo="none">hibernate.cfg.xml</property> + </emphasis> or <emphasis> + <property moreinfo="none">hibernate.properties</property> + </emphasis> with a fileset.</para> + + <para>The <emphasis> + <property moreinfo="none"> + <literal moreinfo="none"><jdbcconfiguration></literal> + </property> + </emphasis> has the same attributes as a <emphasis> + <property moreinfo="none"> + <literal moreinfo="none"><configuration></literal> + </property> + </emphasis> plus the following additional attributes:</para> + + <programlisting format="linespecific" role="XML"><![CDATA[<jdbcconfiguration + ... + packagename="package.name" + revengfile="hibernate.reveng.xml" + reversestrategy="ReverseEngineeringStrategy classname" + detectmanytomany="true|false" + detectoptmisticlock="true|false" +> + ... + </jdbcconfiguration>]]></programlisting> + + <table frame="topbot"> + <title>Jdbcconfiguration attributes</title> + + <tgroup cols="3"> + + <colspec colwidth="0.3*"></colspec> + + <colspec colwidth="1.0*"></colspec> + + <colspec colwidth="0.3*"></colspec> + + + <thead> + <row> + <entry>Attribute name</entry> + + <entry>Definition</entry> + + <entry>Attribute use</entry> + </row> + </thead> + + <tbody> + <row> + <entry> + <para>packagename</para> + </entry> + + <entry> + <para>The default package name to use when mappings for classes are created</para> + </entry> + + <entry> + <para>Optional</para> + </entry> + </row> + + <row> + <entry> + <para>revengfile</para> + </entry> + + <entry> + <para>The name of a property file, e.g. "hibernate.properties"</para> + </entry> + + <entry> + <para>Optional</para> + </entry> + </row> + + <row> + <entry> + <para>reversestrategy</para> + </entry> + + <entry> + <para>Name of a class that implements + org.hibernate.cfg.reveng.ReverseEngineeringStrategy. Used for setting up the + strategy the tools will use to control the reverse engineering, e.g. naming of + properties, which tables to include/exclude etc. Using a class instead of (or as + addition to) a reveng.xml file gives you full programmatic control of the reverse + engineering.</para> + </entry> + + <entry> + <para>Optional</para> + </entry> + </row> + + + <row> + <entry> + <para>detectManytoMany</para> + </entry> + + <entry> + <para>If true, tables which are pure many-to-many link tables will be mapped as + such. A pure many-to-many table is one which primary-key contains exactly two + foreign-keys pointing to other entity tables and has no other columns.</para> + </entry> + + <entry> + <para>Default: true</para> + </entry> + </row> + + <row> + <entry> + <para>detectOptimisticLock</para> + </entry> + + <entry> + <para>If true, columns named VERSION or TIMESTAMP with appropriate types will be + mapped with the appropriate optimistic locking corresponding to + <version> or <timestamp>.</para> + </entry> + + <entry> + <para>Default: true</para> + </entry> + </row> + + </tbody> + + </tgroup> + </table> + + <section> + <title>Example</title> + + <para>Here is an example of using <emphasis> + <property moreinfo="none"> + <literal moreinfo="none"><jdbcconfiguration></literal> + </property> + </emphasis> to generate Hibernate xml mappings via <emphasis> + <property moreinfo="none"><hbm2hbmxml></property>.</emphasis> The connection settings here + is read from a <emphasis> + <property moreinfo="none"> hibernate.properties </property> + </emphasis> file but could just as well have been read from a <emphasis> + <property moreinfo="none">hibernate.cfg.xml</property>. </emphasis></para> + + <programlisting format="linespecific" role="XML"><![CDATA[<hibernatetool> + <jdbcconfiguration propertyfile="etc/hibernate.properties" /> + <hbm2hbmxml destdir="${build.dir}/src" /> +</hibernatetool> +]]></programlisting> + </section> + </section> + </section> + + <section> + <title>Exporters</title> + + <para>Exporters are the parts that do the actual job of converting the hibernate metamodel into + various artifacts, mainly code. The following section describes the current supported set of + exporters in the <property moreinfo="none">Hibernate Tool</property> distribution. It is also possible for + userdefined exporters, that is done through the <emphasis> + <property moreinfo="none"> + <literal moreinfo="none"><hbmtemplate></literal> + </property> + </emphasis> exporter.</para> + + <section> + <title>Database schema exporter (<hbm2ddl>)</title> + + <para><emphasis> + <property moreinfo="none"><hbm2ddl></property> + </emphasis> lets you run schemaexport and schemaupdate which generates the appropriate SQL + DDL and allow you to store the result in a file or export it directly to the database. + Remember that if a custom naming strategy is needed it is placed on the configuration + element.</para> + + <programlisting format="linespecific" role="XML"><![CDATA[<hbm2ddl + export="true|false" + update="true|false" + drop="true|false" + create="true|false" + outputfilename="filename.ddl" + delimiter=";" + format="true|false" + haltonerror="true|false" + >]]></programlisting> + + <table frame="topbot"> + <title>Hbm2ddl exporter attributes</title> + + <tgroup cols="3"> + + <colspec colwidth="0.3*"></colspec> + + <colspec colwidth="1.0*"></colspec> + + <colspec colwidth="0.3*"></colspec> + + + <thead> + <row> + <entry>Attribute name</entry> + + <entry>Definition</entry> + + <entry>Attribute use</entry> + </row> + </thead> + + <tbody> + <row> + <entry> + <para>export</para> + </entry> + + <entry> + <para>Executes the generated statements against the database</para> + </entry> + + <entry> + <para>Default: true</para> + </entry> + </row> + + <row> + <entry> + <para>update</para> + </entry> + + <entry> + <para>Try and create an update script representing the "delta" + between what is in the database and what the mappings specify. Ignores + create/update attributes. (<emphasis>Do *not* use against production databases, no + guarantees at all that the proper delta can be generated nor that the underlying + database can actually execute the needed operations</emphasis>).</para> + </entry> + + <entry> + <para>Default: false</para> + </entry> + </row> + + <row> + <entry> + <para>drop</para> + </entry> + + <entry> + <para>Output will contain drop statements for the tables, indices and + constraints</para> + </entry> + + <entry> + <para>Default: false</para> + </entry> + </row> + + + <row> + <entry> + <para>create</para> + </entry> + + <entry> + <para>Output will contain create statements for the tables, indices and + constraints</para> + </entry> + + <entry> + <para>Default: true</para> + </entry> + </row> + + <row> + <entry> + <para>outputfilename</para> + </entry> + + <entry> + <para>If specified the statements will be dumped to this file</para> + </entry> + + <entry> + <para>Optional</para> + </entry> + </row> + + <row> + <entry> + <para>delimiter</para> + </entry> + + <entry> + <para>If specified the statements will be dumped to this file</para> + </entry> + + <entry> + <para>Default: ";"</para> + </entry> + </row> + + <row> + <entry> + <para>format</para> + </entry> + + <entry> + <para>Apply basic formatting to the statements</para> + </entry> + + <entry> + <para>Default: false</para> + </entry> + </row> + + <row> + <entry> + <para>haltonerror</para> + </entry> + + <entry> + <para>Halt build process if an error occurs</para> + </entry> + + <entry> + <para>Default: false</para> + </entry> + </row> + </tbody> + + </tgroup> + </table> + + <section> + <title>Example</title> + + <para>Basic example of using <emphasis> + <property moreinfo="none"><hbm2ddl></property>, </emphasis> which does not export to the + database but simply dumps the sql to a file named <emphasis> + <property moreinfo="none">sql.ddl</property>. </emphasis></para> + + <programlisting format="linespecific" role="XML"><![CDATA[<hibernatetool destdir="${build.dir}/generated"> + <configuration configurationfile="hibernate.cfg.xml"/> + <hbm2ddl export="false" outputfilename="sql.ddl"/> +</hibernatetool>]]></programlisting> + </section> + </section> + + <section> + <title>POJO java code exporter (<literal moreinfo="none"><hbm2java></literal>)</title> + + <para><emphasis> + <property moreinfo="none"><hbm2java></property> + </emphasis> is a java codegenerator. Options for controlling whether JDK 5 syntax can be + used and whether the POJO should be annotated with EJB3/Hibernate Annotations.</para> + + <programlisting format="linespecific" role="XML"><![CDATA[<hbm2java + jdk5="true|false" + ejb3="true|false" +>]]></programlisting> + + <table frame="topbot"> + <title>Hbm2java exporter attributes</title> + + <tgroup cols="3"> + + <colspec colwidth="0.3*"></colspec> + + <colspec colwidth="1.0*"></colspec> + + <colspec colwidth="0.3*"></colspec> + + + <thead> + <row> + <entry>Attribute name</entry> + + <entry>Definition</entry> + + <entry>Default value</entry> + </row> + </thead> + + <tbody> + <row> + <entry> + <para>jdk</para> + </entry> + + <entry> + <para>Code will contain JDK 5 constructs such as generics and static imports</para> + </entry> + + <entry> + <para>False</para> + </entry> + </row> + + <row> + <entry> + <para>ejb3</para> + </entry> + + <entry> + <para>Code will contain EJB 3 features, e.g. using annotations from + javax.persistence and org.hibernate.annotations</para> + </entry> + + <entry> + <para>False</para> + </entry> + </row> + + </tbody> + + </tgroup> + </table> + + <section> + <title>Example</title> + + <para>Basic example of using <emphasis> + <property moreinfo="none"><hbm2java></property> + </emphasis> to generate POJO's that utilize jdk5 constructs.</para> + + <programlisting format="linespecific" role="XML"><![CDATA[<hibernatetool destdir="${build.dir}/generated"> + <configuration configurationfile="hibernate.cfg.xml"/> + <hbm2java jdk5="true"/> +</hibernatetool>]]></programlisting> + </section> + </section> + + <section> + <title>Hibernate Mapping files exporter (<literal moreinfo="none"><hbm2hbmxml></literal>)</title> + + <para><emphasis> + <property moreinfo="none"><hbm2hbmxml></property> + </emphasis> generates a set of .hbm files. Intended to be used together with a <emphasis> + <property moreinfo="none"><jdbcconfiguration></property> + </emphasis> when performing reverse engineering, but can be used with any kind of + configuration. e.g. to convert from annotation based pojo's to <emphasis> + <property moreinfo="none">hbm.xml</property>. </emphasis></para> + + <note> + <title>Note:</title> + <para>Not every possible mapping transformation is possible/implemented (contributions + welcome) so some hand editing might be necessary.</para> + </note> + + <programlisting format="linespecific" role="XML"><![CDATA[<hbm2hbmxml/>]]></programlisting> + + <section> + <title>Example</title> + + <para>Basic usage of <emphasis> + <property moreinfo="none"><hbm2hbmxml></property>. </emphasis></para> + + <programlisting format="linespecific" role="XML"><![CDATA[<hibernatetool destdir="${build.dir}/generated"> + <configuration configurationfile="hibernate.cfg.xml"/> + <hbm2hbmxml/> +</hibernatetool>]]></programlisting> + + <para><emphasis> + <property moreinfo="none"><hbm2hbmxml></property> + </emphasis> is normally used with a <emphasis> + <property moreinfo="none"><jdbcconfiguration></property> + </emphasis> like in the above example, but any other configuration can also be used to + convert between the different ways of performing mappings. Here is an example of that, + using an <emphasis> + <property moreinfo="none"><annotationconfiguration></property> + </emphasis>.</para> + + <note> + <title>Note:</title> + <para>Not all conversions are implemented (contributions welcome), so some hand editing + might be necessary.</para> + </note> + + <programlisting format="linespecific" role="XML"><![CDATA[<hibernatetool destdir="${build.dir}/generated"> + <annotationconfiguration configurationfile="hibernate.cfg.xml"/> + <hbm2hbmxml/> +</hibernatetool>]]></programlisting> + </section> + </section> + + <section> + <title>Hibernate Configuration file exporter (<literal moreinfo="none"><hbm2cfgxml></literal>)</title> + + <para><emphasis> + <property moreinfo="none"><hbm2cfgxml></property> + </emphasis> generates a <emphasis> + <property moreinfo="none">hibernate.cfg.xml</property>. </emphasis> Intended to be used together with a <emphasis> + <property moreinfo="none"><jdbcconfiguration></property> + </emphasis> when performing reverse engineering, but it can be used with any kind of + configuration. The <emphasis> + <property moreinfo="none"><hbm2cfgxml></property> + </emphasis> will contain the properties used and adds mapping entries for each mapped class.</para> + + <programlisting format="linespecific" role="XML"><![CDATA[<hbm2cfgxml + ejb3="true|false" +/> +]]></programlisting> + + <table frame="topbot"> + <title>Hbm2cfgxml exporter attribute</title> + + <tgroup cols="3"> + + <colspec colwidth="0.3*"></colspec> + + <colspec colwidth="1.0*"></colspec> + + <colspec colwidth="0.3*"></colspec> + + + <thead> + <row> + <entry>Attribute name</entry> + + <entry>Definition</entry> + + <entry>Default value</entry> + </row> + </thead> + + <tbody> + + <row> + <entry> + <para>ejb3</para> + </entry> + + <entry> + <para>The generated cfg.xml will have <mapping class=".."/>, opposed + to <mapping resource="..."/> for each mapping.</para> + </entry> + + <entry> + <para>False</para> + </entry> + </row> + + </tbody> + + </tgroup> + </table> + + </section> + + <section> + <title>Documentation exporter (<literal moreinfo="none"><hbm2doc></literal>)</title> + + <para><emphasis> + <property moreinfo="none"><hbm2doc></property> + </emphasis> generates html documentation a'la javadoc for the database schema et.al.</para> + + <programlisting format="linespecific" role="XML"><![CDATA[<hbm2doc/>]]></programlisting> + </section> + + <section> + <title>Query exporter (<query>)</title> + + <para><emphasis> + <property moreinfo="none"><query></property> + </emphasis> is used to execute a HQL query statements and optionally sends the output to a + file. It can be used for verifying the mappings and for basic data extraction.</para> + + <programlisting format="linespecific" role="XML"><![CDATA[<query + destfile="filename"> + <hql>[a HQL query string]</hql> +</query> +]]></programlisting> + + <para>Currently one session is opened and used for all queries and the query is executed via + the list() method. In the future more options might become available, like performing + executeUpdate(), use named queries and etc.</para> + + <para></para> + + <section> + <title>Examples</title> + + <para>The simplest usage of <emphasis> + <property moreinfo="none"><query></property> + </emphasis> will just execute the query without dumping to a file. This can be used to + verify that queries can actually be performed.</para> + + <programlisting format="linespecific" role="XML"><![CDATA[<hibernatetool> + <configuration configurationfile="hibernate.cfg.xml"/> + <query>from java.lang.Object</query> +</hibernatetool>]]></programlisting> + + <para>Multiple queries can be executed by nested <emphasis> + <property moreinfo="none"><hql></property> + </emphasis> elements. In this example we also let the output be dumped to <emphasis> + <property moreinfo="none">queryresult.txt</property>. </emphasis></para> + + <note> + <title>Note:</title> + <para> Currently the dump is simply a call to toString on each element.</para> + </note> + + <programlisting format="linespecific" role="XML"><![CDATA[<hibernatetool> + <configuration configurationfile="hibernate.cfg.xml"/> + <query destfile="queryresult.txt"> + <hql>select c.name from Customer c where c.age > 42</hql> + <hql>from Cat</hql> +</hibernatetool>]]></programlisting> + + </section> + </section> + + <section id="hbmtemplate"> + <title>Generic Hibernate metamodel exporter (<literal moreinfo="none"><hbmtemplate></literal>)</title> + + <para>Generic exporter that can be controlled by a user provides a template or class.</para> + + <programlisting format="linespecific" role="XML"><![CDATA[<hbmtemplate + filepattern="{package-name}/{class-name}.ftl" + template="somename.ftl" + exporterclass="Exporter classname" +/>]]></programlisting> + + <note> + <title>Note:</title> + <para>Previous versions of the tools used Velocity. We are now using Freemarker which + provides us much better exception and error handling.</para> + </note> + + <section> + <title>Exporter via <hbmtemplate></title> + + <para>The following is an example of reverse engineering via <emphasis> + <property moreinfo="none"><jdbcconfiguration></property> + </emphasis> and usage of a custom Exporter via the <emphasis> + <property moreinfo="none"><hbmtemplate></property> + </emphasis>.</para> + + <programlisting format="linespecific" role="XML"><![CDATA[ <hibernatetool destdir="${destdir}"> + <jdbcconfiguration + configurationfile="hibernate.cfg.xml" + packagename="my.model"/> + +  + <property key="appname" value="Registration"/> + <property key="shortname" value="crud"/> + + <hbmtemplate + exporterclass="my.own.Exporter" + filepattern="."/> + +</hibernatetool> +]]></programlisting> + + </section> + <section> + <title>Relevant Resources Links</title> + + <para>Read more about <ulink url="http://velocity.apache.org/">Velocity</ulink> and <ulink url="http://freemarker.org/">Freemarker</ulink> to find out why using the last is better + or refer to Max Andersen discussion on the topic in <ulink url="http://in.relation.to/2110.lace;jsessionid=3462F47B17556604C15DF1B96572E940">"A story about FreeMarker and Velocity"</ulink>.</para> + </section> + </section> + </section> + + + + <section> + <title>Using properties to configure Exporters</title> + + <para>Exporters can be controlled by user properties. The user properties are specified via <emphasis> + <property moreinfo="none"><property></property> + </emphasis> or <emphasis> + <property moreinfo="none"> + <literal moreinfo="none"><propertyset></literal> + </property> + </emphasis> and each exporter will have access to them directly in the templates and via + <property moreinfo="none">Exporter.setProperties()</property>.</para> + + <section> + <title><literal moreinfo="none"><property></literal> and + <literal moreinfo="none"><propertyset></literal></title> + + <para>The <emphasis> + <property moreinfo="none"><property></property> + </emphasis> allows you bind a string value to a key. The value will be available in the + templates via <emphasis> + <property moreinfo="none">$<key></property> + </emphasis>. The following example will assign the string value <emphasis> + <property moreinfo="none">"true"</property> + </emphasis> to the variable <emphasis> + <property moreinfo="none">$descriptors</property> + </emphasis>.</para> + + <programlisting format="linespecific" role="XML"><![CDATA[<property key="descriptors" value="true"/>]]></programlisting> + + <para>Most times using <emphasis> + <property moreinfo="none"> + <literal moreinfo="none"><property></literal> + </property> + </emphasis> is enough for specifying the properties needed for the exporters. Still the ant + tools supports the notion of <emphasis> + <property moreinfo="none"> + <literal moreinfo="none"><propertyset></literal> + </property> + </emphasis> that is used for grouping a set of properties. More about the functionality of <emphasis> + <property moreinfo="none"> + <literal moreinfo="none"><propertyset></literal> + </property> + </emphasis> is explained in detail in the <ulink url="http://ant.apache.org/manual/">Ant + manual</ulink>.</para> + </section> + + <section> + <title>Getting access to user specific classes</title> + + <para>If the templates need to access some user class it becomes possible by specifying a <emphasis> + <property moreinfo="none">"toolclass"</property> + </emphasis> in the properties.</para> + + <programlisting format="linespecific" role="XML"><![CDATA[<property key="hibernatetool.sometool.toolclass" value="x.y.z.NameOfToolClass"/> +]]></programlisting> + + <para>Placing the above <emphasis> + <property moreinfo="none"> + <literal moreinfo="none"><property></literal> + </property> + </emphasis> tag in <emphasis> + <property moreinfo="none"> + <literal moreinfo="none"><hibernatetool></literal> + </property> + </emphasis> or inside any exporter will automatically create an instance of + <literal moreinfo="none">x.y.z.NameOfToolClass</literal> and it will be available in the templates as + <literal moreinfo="none">$sometool</literal>. This is useful to delegate logic and code generation to java + code instead of placing such logic in the templates.</para> + + <section> + <title>Example</title> + + <para>Here is an example that uses <emphasis> + <property moreinfo="none"><hbmtemplate></property> + </emphasis> together with <emphasis> + <property moreinfo="none"><property></property> + </emphasis> which will be available to the templates/exporter. </para> + <note> + <title>Note:</title> + <para> This example actually simulates what <hbm2java> actually does.</para> + </note> + + <programlisting format="linespecific" role="XML"><![CDATA[<hibernatetool destdir="${build.dir}/generated"> +<configuration + configurationfile="etc/hibernate.cfg.xml"/> + <hbmtemplate + templateprefix="pojo/" + template="pojo/Pojo.ftl" + filepattern="{package-name}/{class-name}.java"> + <property key="jdk5" value="true" /> + <property key="ejb3" value="true" /> + </hbmtemplate> +</hibernatetool> +]]></programlisting> + </section> + </section> + </section> +</chapter> + + +<chapter id="reverseengineering" xml:base="file:///home/ochikvina/WORK/for_compare/trunk/hibernatetools/docs/reference/en/modules/reverseengineering.xml"> + <title>Controlling reverse engineering</title> + + <para>When using the <emphasis> + <property moreinfo="none"><jdbcconfiguration></property>, </emphasis> the ant task will read the + database metadata and thus will perform a reverse engineering of the database schema into a + normal Hibernate Configuration. It is from this object e.g. <emphasis> + <property moreinfo="none"><hbm2java></property> + </emphasis>can generate other artifacts such as <emphasis> + <property moreinfo="none">.java</property> + </emphasis>, <emphasis> + <property moreinfo="none">.hbm.xml</property> + </emphasis> etc.</para> + + <para>To govern this process <property moreinfo="none">Hibernate</property> uses a reverse engineering strategy. A + reverse engineering strategy is mainly called to provide more java like names for tables, column + and foreignkeys into classes, properties and associations. It also used to provide mappings from + SQL types to <property moreinfo="none">Hibernate</property> types. The strategy can be customized by a user. The + user can even provide its own custom reverse engineering strategy if the provided strategy is + not enough, or simply just provide a small part of the strategy and delegate the rest to the + default strategy.</para> + + <para>Thus, further in this chapter we will discuss how you can configure the process of a reverse + engineering, what default reverse engineering strategy includes as well as some custom concepts.</para> + + <section> + <title>Default reverse engineering strategy</title> + + <para>The default strategy uses some rules for mapping JDBC artifact names to java artifact + names. It also provide basic typemappings from JDBC types to <property moreinfo="none">Hibernate</property> + types. It is the default strategy that uses the packagename attribute to convert a table name + to a fully qualified classname.</para> + </section> + + <section id="hibernaterevengxmlfile"> + <title>hibernate.reveng.xml file</title> + + <para>To have fine control over the process a <emphasis> + <property moreinfo="none">hibernate.reveng.xml</property> + </emphasis> file can be provided. In this file you can specify type mappings and table + filtering. This file can be created by hand (it's just basic XML) or you can use the + <ulink url="http://www.hibernate.org/30.html">Hibernate plugins</ulink> which have a + specialized editor.</para> + + <note> + <title>Note:</title> + <para>Many databases are case-sensitive with their names and thus if you cannot make some + table match and you are sure it is not excluded by a <table-filter> then check + if the case matches; most databases stores table names in uppercase.</para> + </note> + + <para>Below you can see an example of a <emphasis> + <property moreinfo="none">reveng.xml</property>. </emphasis> Following the example gives you more details + about the format.</para> + + <programlisting format="linespecific" role="XML"><![CDATA[<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE hibernate-reverse-engineering + SYSTEM "http://hibernate.sourceforge.net/hibernate-reverse-engineering-3.0.dtd" > + +<hibernate-reverse-engineering> + +<type-mapping> +  + <sql-type jdbc-type="VARCHAR" length='20' hibernate-type="SomeUserType" /> + <sql-type jdbc-type="VARCHAR" length='1' hibernate-type="yes_no" /> +  + <sql-type jdbc-type="NUMERIC" precision='1' hibernate-type="boolean" /> +  + <sql-type jdbc-type="NUMERIC" hibernate-type="long" /> +</type-mapping> + + +<table-filter match-name="BIN$.*" exclude="true" /> + + +<table-filter match-name="DoNotWantIt" exclude="true" /> + + +<table-filter match-catalog="BAD" match-schema="SCHEMA" match-name=".*" exclude="true" /> + + +<table name="ORDERS"> + <primary-key> +  + <generator class="sequence"> + <param name="table">seq_table</param> + </generator> + <key-column name="CUSTID"/> + </primary-key> + <column name="NAME" property="orderName" type="string" /> +  + <foreign-key constraint-name="ORDER_CUST"> + <many-to-one property="customer"/> + <set property="orders"/> + </foreign-key> +  + <foreign-key constraint-name="ADDRESS_PERSON"> + <one-to-one exclude="false"/> + <inverse-one-to-one exclude="true"/> + </foreign-key> +</table> + +</hibernate-reverse-engineering>]]></programlisting> + + + <section> + <title>Schema Selection (<schema-selection>)</title> + + <para><emphasis> + <property moreinfo="none"><schema-selection></property> + </emphasis> is used to drive which schemas the reverse engineering will try and + process.</para> + + <para>By default the reverse engineering will read all schemas and then use <emphasis> + <property moreinfo="none"><table-filter></property> + </emphasis> to decide which tables get reverse engineered and which do not; this makes it + easy to get started but can be inefficient on databases with many schemas.</para> + + <para>With <emphasis> + <property moreinfo="none"><schema-selection></property> + </emphasis> it is thus possible to limit the actual processed schemas and thus significantly + speed-up the reverse engineering. <emphasis> + <property moreinfo="none"><table-filter></property> + </emphasis> is still used to then decide which tables will be included/excluded.</para> + + <note> + <title>Note:</title> + <para>If no <literal moreinfo="none"><schema-selection></literal> is specified, the reverse + engineering works as if all schemas should be processed. This is equal to: + <![CDATA[<schema-selection/>]]>. Which in turn is equal to: + <![CDATA[<schema-selection match-catalog=".*" match-schema=".*" match-table=".*"/>]]></para> + </note> + + <section> + <title>Examples</title> + + <para>The following will process all tables from <emphasis> + <property moreinfo="none">"MY_SCHEMA"</property>. + </emphasis></para> + + <programlisting format="linespecific" role="XML"><![CDATA[<schema-selection match-schema="MY_SCHEMA"/>]]></programlisting> + + <para>It is possible to have multiple <literal moreinfo="none">schema-selection</literal>'s to support + multi-schema reading or simply to limit the processing to very specific tables. The + following example processes all tables in <emphasis> + <property moreinfo="none">"MY_SCHEMA"</property>, + </emphasis> a specific <emphasis> + <property moreinfo="none">"CITY"</property> + </emphasis> table plus all tables that starts with <emphasis> + <property moreinfo="none">"CODES_"</property> + </emphasis> in <emphasis> + <property moreinfo="none">"COMMON_SCHEMA"</property>. + </emphasis></para> + + <programlisting format="linespecific" role="XML"><![CDATA[<schema-selection match-schema="MY_SCHEMA"/> +<schema-selection match-schema="COMMON_SCHEMA" match-table="CITY"/> +<schema-selection match-schema="COMMON_SCHEMA" match-table="CODES_.*"/>]]></programlisting> + </section> + </section> + + <section id="type_map"> + <title>Type mappings (<type-mapping>)</title> + + <para>The <emphasis> + <property moreinfo="none"><type-mapping></property> + </emphasis> section specifies how the JDBC types found in the database should be mapped to + Hibernate types. e.g. <emphasis> + <property moreinfo="none">java.sql.Types.VARCHAR</property></emphasis> with a length of 1 should be mapped to the + Hibernate type <emphasis> + <property moreinfo="none">yes_no</property></emphasis> or <emphasis> + <property moreinfo="none">java.sql.Types.NUMERIC</property></emphasis> should generally just be + converted to the Hibernate type <literal moreinfo="none">long</literal>.</para> + + <programlisting format="linespecific" role="XML"><![CDATA[<type-mapping> + <sql-type + jdbc-type="integer value or name from java.sql.Types" + length="a numeric value" + precision="a numeric value" + scale="a numeric value" + not-null="true|false" + hibernate-type="hibernate type name" + /> +</type-mapping>]]></programlisting> + + <para>The number of attributes specified and the sequence of the <literal moreinfo="none">sql-type</literal>'s + is important. Meaning that <property moreinfo="none">Hibernate</property> will search for the most specific + first, and if no specific match is found it will seek from top to bottom when trying to + resolve a type mapping.</para> + + <section> + <title>Example</title> + + <para>The following is an example of a type-mapping which shows the flexibility and the + importance of ordering of the type mappings.</para> + + <programlisting format="linespecific" role="XML"><![CDATA[<type-mapping> + <sql-type jdbc-type="NUMERIC" precision="15" hibernate-type="big_decimal"/> + <sql-type jdbc-type="NUMERIC" not-null="true" hibernate-type="long" /> + <sql-type jdbc-type="NUMERIC" not-null="false" hibernate-type="java.lang.Long" /> + <sql-type jdbc-type="VARCHAR" length="1" not-null="true" + hibernate-type="java.lang.Character"/> + <sql-type jdbc-type="VARCHAR" hibernate-type="your.package.TrimStringUserType"/> + <sql-type jdbc-type="VARCHAR" length="1" hibernate-type="char"/> + <sql-type jdbc-type="VARCHAR" hibernate-type="string"/> +</type-mapping>]]></programlisting> + + <para>The following table shows how this affects an example table named <emphasis> + <property moreinfo="none">CUSTOMER</property>:</emphasis></para> + + <table frame="topbot"> + <title>sql-type examples</title> + + <tgroup cols="7"> + <colspec colwidth="0.4*"></colspec> + + <colspec colwidth="0.4*"></colspec> + + <colspec colwidth="0.2*"></colspec> + + <colspec colwidth="0.3*"></colspec> + + <colspec colwidth="0.2*"></colspec> + + <colspec colwidth="1.0*"></colspec> + + <colspec colwidth="0.7*"></colspec> + + <thead> + <row> + <entry>Column</entry> + + <entry>jdbc-type</entry> + + <entry>length</entry> + + <entry>precision</entry> + + <entry>not-null</entry> + + <entry>Resulting hibernate-type</entry> + + <entry>Rationale</entry> + </row> + </thead> + + <tbody> + <row> + <entry>ID</entry> + + <entry>INTEGER</entry> + + <entry></entry> + + <entry>10</entry> + + <entry>true</entry> + + <entry>int</entry> + + <entry>Nothing is defined for INTEGER. Falling back to default behavior.</entry> + </row> + + <row> + <entry>NAME</entry> + + <entry>VARCHAR</entry> + + <entry>30</entry> + + <entry></entry> + + <entry>false</entry> + + <entry>your.package.TrimStringUserType</entry> + + <entry>No type-mapping matches length=30 and not-null=false, but type-mapping + matches the 2 mappings which only specifies VARCHAR. The type-mapping that comes + first is chosen.</entry> + </row> + + <row> + <entry>INITIAL</entry> + + <entry>VARCHAR</entry> + + <entry>1</entry> + + <entry></entry> + + <entry>false</entry> + + <entry>char</entry> + + <entry>Even though there is a generic match for VARCHAR, the more specific + type-mapping for VARCHAR with not-null="false" is chosen. The first VARCHAR + sql-type matches in length but has no value for not-null and thus is not + considered.</entry> + </row> + + <row> + <entry>CODE</entry> + + <entry>VARCHAR</entry> + + <entry>1</entry> + + <entry></entry> + + <entry>true</entry> + + <entry>java.lang.Character</entry> + + <entry>The most specific VARCHAR with not-null="true" is selected</entry> + </row> + + <row> + <entry>SALARY</entry> + + <entry>NUMERIC</entry> + + <entry></entry> + + <entry>15</entry> + + <entry>false</entry> + + <entry>big_decimal</entry> + + <entry>There is a precise match for NUMERIC with precision 15</entry> + </row> + + <row> + <entry>AGE</entry> + + <entry>NUMERIC</entry> + + <entry></entry> + + <entry>3</entry> + + <entry>false</entry> + + <entry>java.lang.Long</entry> + + <entry>type-mapping for NUMERIC with not-null="false"</entry> + </row> + </tbody> + </tgroup> + </table> + + <para></para> + </section> + </section> + + <section> + <title>Table filters (<table-filter>)</title> + + <para>The <emphasis> + <property moreinfo="none"><table-filter></property> + </emphasis> let you specify matching rules for performing general filtering/setup for + tables, e.g. let you include or exclude specific tables based on the schema or even a + specific prefix.</para> + + <programlisting format="linespecific" role="XML"><![CDATA[<table-filter + match-catalog="catalog_matching_rule" + match-schema="schema_matching_rule" + match-name="table_matching_rule" + exclude="true|false" + package="package.name" +/>]]></programlisting> + + <table frame="topbot"> + <title>Table-filter attributes</title> + + <tgroup cols="3"> + + <colspec colwidth="0.3*"></colspec> + + <colspec colwidth="1.0*"></colspec> + + <colspec colwidth="0.3*"></colspec> + + + <thead> + <row> + <entry>Attribute name</entry> + + <entry>Definition</entry> + + <entry>Default value</entry> + </row> + </thead> + + <tbody> + <row> + <entry><para>match-catalog</para></entry> + + <entry><para>Pattern for matching catalog part of the table</para></entry> + + <entry><para>.*</para></entry> + </row> + + <row> + <entry><para>match-schema</para></entry> + + <entry><para>Pattern for matching schema part of the table</para></entry> + + <entry><para>.*</para></entry> + </row> + + <row> + <entry><para>match-table</para></entry> + + <entry><para>Pattern for matching table part of the table</para></entry> + + <entry><para>.*</para></entry> + </row> + + <row> + <entry><para>exclude </para></entry> + + <entry><para>If true the table will not be part of the reverse + engineering</para></entry> + + <entry><para>false</para></entry> + </row> + + <row> + <entry><para>package</para></entry> + + <entry><para>The default package name to use for classes based on tables + matched by this table-filter</para></entry> + + <entry><para>""</para></entry> + </row> + </tbody> + + </tgroup> + </table> + + </section> + + <section id="tab_and_col"> + <title>Specific table configuration (<table>)</title> + + <para><emphasis> + <property moreinfo="none"><table></property> + </emphasis> allows you to provide explicit configuration on how a table should be reverse + engineered. Amongst other things it allows controlling over the naming of a class for the + table, specifying which identifier generator should be used for the primary key etc.</para> + + <programlisting format="linespecific" role="XML"><![CDATA[<table + catalog="catalog_name" + schema="schema_name" + name="table_name" + class="ClassName" +> + <primary-key.../> + <column.../> + <foreign-key.../> + </table>]]></programlisting> + + <table frame="topbot"> + <title>Table attributes</title> + + <tgroup cols="3"> + + <colspec colwidth="0.3*"></colspec> + + <colspec colwidth="1.0*"></colspec> + + <colspec colwidth="0.3*"></colspec> + + + <thead> + <row> + <entry>Attribute name</entry> + + <entry>Definition</entry> + + <entry>Attribute use</entry> + </row> + </thead> + + <tbody> + <row> + <entry><para>catalog</para></entry> + + <entry><para>Catalog name for a table. It has to be specified if you are + reverse engineering multiple catalogs or if it is not equal to + hiberante.default_catalog.</para></entry> + + <entry><para>Optional</para></entry> + </row> + + <row> + <entry><para>schema</para></entry> + + <entry><para>Schema name for a table. It has to be specified if you are + reverse engineering multiple schemas or if it is not equal to + hiberante.default_schema.</para></entry> + + <entry><para>Optional</para></entry> + </row> + + <row> + <entry><para>name</para></entry> + + <entry><para>Name for a table.</para></entry> + + <entry><para>Required</para></entry> + </row> + + <row> + <entry><para>class</para></entry> + + <entry><para>The class name for a table. Default name is a camelcase version + of the table name.</para></entry> + + <entry><para>Optional</para></entry> + </row> + + </tbody> + + </tgroup> + </table> + + <section> + <title><primary-key></title> + + <para>A <emphasis> + <property moreinfo="none"><primary-key></property> + </emphasis> allows you to define a primary-key for tables that don't have it + defined in the database, and probably more importantly it allows you to define which + identifier strategy should be used (even for already existing primary-key's).</para> + + <programlisting format="linespecific" role="XML"><![CDATA[<primary-key + <generator class="generatorname"> + <param name="param_name">parameter value</param> + </generator> + <key-column...> + </primary-key>]]></programlisting> + + <table frame="topbot"> + <title>Primary-key attributes</title> + + <tgroup cols="3"> + + <colspec colwidth="0.3*"></colspec> + + <colspec colwidth="1.0*"></colspec> + + <colspec colwidth="0.3*"></colspec> + + + <thead> + <row> + <entry>Attribute name</entry> + + <entry>Definition</entry> + + <entry>Attribute use</entry> + </row> + </thead> + + <tbody> + <row> + <entry><para>generator/class</para></entry> + + <entry><para>Defines which identifier generator should be used. + The class name is any hibernate short hand name or fully qualified class name for an + identifier strategy.</para></entry> + + <entry><para>Optional</para></entry> + </row> + + <row> + <entry><para>generator/param</para></entry> + + <entry><para>Allows to specify which parameter with a name and + value should be passed to the identifier generator.</para></entry> + + <entry><para>Optional</para></entry> + </row> + + <row> + <entry><para>key-column</para></entry> + + <entry><para>Specifies which column(s ) the primary-key consists of. A + key-column is same as column, but does not have the exclude property.</para></entry> + + <entry><para>Optional</para></entry> + </row> + + </tbody> + + </tgroup> + </table> + + </section> + + <section> + <title><column></title> + + <para>With a <emphasis> + <property moreinfo="none"><column></property> + </emphasis> it is possible to explicitly name the resulting property for a column. It is + also possible to redefine what jdbc and/or Hibernate type a column should be processed as + and finally it is possible to completely exclude a column from processing.</para> + + <programlisting format="linespecific" role="XML"><![CDATA[<column + name="column_name" + jdbc-type="java.sql.Types type" + type="hibernate_type" + property="propertyName" + exclude="true|false" +/>]]></programlisting> + + <table frame="topbot"> + <title>Column attributes</title> + + <tgroup cols="3"> + + <colspec colwidth="0.3*"></colspec> + + <colspec colwidth="1.0*"></colspec> + + <colspec colwidth="0.3*"></colspec> + + + <thead> + <row> + <entry>Attribute name</entry> + + <entry>Definition</entry> + + <entry>Attribute use</entry> + </row> + </thead> + + <tbody> + <row> + <entry><para>name</para></entry> + + <entry><para>Column name</para></entry> + + <entry><para>Required</para></entry> + </row> + + <row> + <entry><para>jdbc-type</para></entry> + + <entry><para>Which jdbc-type this column should be processed as. A + value from java.sql.Types, either numerical (93) or the constant name + (TIMESTAMP).</para></entry> + + <entry><para>Optional</para></entry> + </row> + + <row> + <entry><para>type</para></entry> + + <entry><para>Which hibernate-type to use for this specific column</para></entry> + + <entry><para>Optional</para></entry> + </row> + + + <row> + <entry><para>property</para></entry> + + <entry><para>What property name will be generated for this + column</para></entry> + + <entry><para>Optional</para></entry> + </row> + + <row> + <entry><para>exclude</para></entry> + + <entry><para>Set to true if this column should be ignored</para></entry> + + <entry><para>default: false</para></entry> + </row> + + </tbody> + + </tgroup> + </table> + + </section> + + <section> + <title><foreign-key></title> + + <para>The <emphasis> + <property moreinfo="none"><foreign-key></property> + </emphasis><diffmk:wrapper diffmk:change="changed"> has two purposes. One for allowing to define foreign-keys in databases that + does not support them or does not have them defined in their schema. Secondly, to allow + defining the name of the resulting properties (many-to-one, one-to-one and one-to-many's).</diffmk:wrapper></para> + + <programlisting format="linespecific" role="XML"><![CDATA[<foreign-key + constraint-name="foreignKeyName" + foreign-catalog="catalogName" + foreign-schema="schemaName" + foreign-table="tableName" + > + <column-ref local-column="columnName" foreign-column="foreignColumnName"/> + <many-to-one + property="aPropertyName" + exclude="true|false"/> + <set + property="aCollectionName" + exclude="true|false" + + <one-to-one + property="aPropertyName" + exclude="true|false"/> + <inverse-one-to-one + property="aPropertyName" + exclude="true|false"/> + </foreign-key>]]></programlisting> + <table frame="topbot"> + <title>Foreign-key attributes</title> + + <tgroup cols="3"> + + <colspec colwidth="0.3*"></colspec> + + <colspec colwidth="1.0*"></colspec> + + <colspec colwidth="0.3*"></colspec> + + + <thead> + <row> + <entry>Attribute name</entry> + + <entry>Definition</entry> + + <entry>Attribute use</entry> + </row> + </thead> + + <tbody> + <row> + <entry><para>constraint-name</para></entry> + + <entry><para><diffmk:wrapper diffmk:change="changed">Name of the foreign key constraint. Important when + naming many-to-one, one-to-one and set. It is the constraint-name that is used to link the + processed foreign-keys with the resulting property names.</diffmk:wrapper></para></entry> + + <entry><para>Required</para></entry> + </row> + + <row> + <entry><para>foreign-catalog</para></entry> + + <entry><para>Name of the foreign table's catalog. (Only + relevant if you want to explicitly define a foreign key).</para></entry> + + <entry><para>Optional</para></entry> + </row> + + <row> + <entry><para>foreign-schema</para></entry> + + <entry><para>Name of the foreign table's schema. (Only relevant + if you want to explicitly define a foreign key).</para></entry> + + <entry><para>Optional</para></entry> + </row> + + + <row> + <entry><para>foreign-table</para></entry> + + <entry><para>Name of the foreign table. (Only relevant if you + want to explicitly define a foreign key).</para></entry> + + <entry><para>Optional</para></entry> + </row> + + <row> + <entry><para>column-ref </para></entry> + + <entry><para>Defines that the foreign-key constraint between a + local-column and foreign-column name. (Only relevant if you want to explicitly + define a foreign key).</para></entry> + + <entry><para>Optional</para></entry> + </row> + + <row> + <entry><para>many-to-one</para></entry> + + <entry><para>Defines that a many-to-one should be created and the + property attribute specifies the name of the resulting property. Exclude can be + used to explicitly define that it should be created or not.</para></entry> + + <entry><para>Optional</para></entry> + </row> + + <row> + <entry><para>set</para></entry> + + <entry><para>Defines that a set should be created based on this foreign-key + and the property attribute specifies the name of the resulting (set) property. + Exclude can be used to explicitly define that it should be created or not.</para></entry> + + <entry><para>Optional</para></entry> + </row> + + <row diffmk:change="added"> + <entry diffmk:change="added"><para diffmk:change="added"><diffmk:wrapper diffmk:change="added">one-to-one</diffmk:wrapper></para></entry> + + <entry diffmk:change="added"><para diffmk:change="added"><diffmk:wrapper diffmk:change="added">Defines that a one-to-one should be created and the + property attribute specifies the name of the resulting property. Exclude can be + used to explicitly define that it should be created or not.</diffmk:wrapper></para></entry> + + <entry diffmk:change="added"><para diffmk:change="added"><diffmk:wrapper diffmk:change="added">Optional</diffmk:wrapper></para></entry> + </row> + + <row diffmk:change="added"> + <entry diffmk:change="added"><para diffmk:change="added"><diffmk:wrapper diffmk:change="added">inverse-one-to-one</diffmk:wrapper></para></entry> + + <entry diffmk:change="added"><para diffmk:change="added"><diffmk:wrapper diffmk:change="added">Defines that an inverse one-to-one should be created based on this foreign-key + and the property attribute specifies the name of the resulting property. + Exclude can be used to explicitly define that it should be created or not.</diffmk:wrapper></para></entry> + + <entry diffmk:change="added"><para diffmk:change="added"><diffmk:wrapper diffmk:change="added">Optional</diffmk:wrapper></para></entry> + </row> + </tbody> + + </tgroup> + </table> + + </section> + </section> + </section> + + <section id="custom-reveng-strategy"> + <title>Custom strategy</title> + + <para>It is possible to implement a user strategy. Such strategy must implement <emphasis> + <property moreinfo="none">org.hibernate.cfg.reveng.ReverseEngineeringStrategy</property>. + </emphasis> It is recommended that one uses the + <property moreinfo="none">DelegatingReverseEngineeringStrategy</property> and provide a public constructor + which takes another <property moreinfo="none">ReverseEngineeringStrategy </property> as an argument. This will + allow you to only implement the relevant methods and provide a fallback strategy. Example of + custom delegating strategy which converts all column names that ends with <emphasis> + <property moreinfo="none">"PK"</property> + </emphasis> into a property named <emphasis> + <property moreinfo="none">"id"</property>. + </emphasis></para> + + <programlisting format="linespecific" role="JAVA"><![CDATA[public class ExampleStrategy extends DelegatingReverseEngineeringStrategy { + + public ExampleStrategy(ReverseEngineeringStrategy delegate) { + super(delegate); + } + + public String columnToPropertyName(TableIdentifier table, String column) { + if(column.endsWith("PK")) { + return "id"; + } else { + return super.columnToPropertyName(table, column); + } + } +}]]></programlisting> + </section> + + <section> + <title>Custom Database Metadata</title> + + <para>By default the reverse engineering is performed by reading using the JDBC database + metadata API. This is done via the class <emphasis> + <property moreinfo="none">org.hibernate.cfg.reveng.dialect.JDBCMetaDataDialect</property> + </emphasis> which is an implementation of <emphasis> + <property moreinfo="none">org.hibernate.cfg.reveng.dialect.MetaDataDialect</property>. + </emphasis></para> + + <para>The default implementation can be replaced with an alternative implementation by setting + the property <emphasis> + <property moreinfo="none">hibernatetool.metadatadialect</property> + </emphasis> to a fully qualified classname for a class that implements + <property moreinfo="none">JDBCMetaDataDialect</property>.</para> + + <para>This can be used to provide database specific optimized metadata reading. If you create an + optimized/better metadata reading for your database it will be a very welcome + contribution.</para> + </section> +</chapter> + + +<chapter id="codegen" xml:base="file:///home/ochikvina/WORK/for_compare/trunk/hibernatetools/docs/reference/en/modules/codegen.xml"> + <title>Controlling POJO code generation</title> + + <para>When using <emphasis> + <property moreinfo="none"><hbm2java></property> + </emphasis> or the eclipse plugin to generate POJO java code you have the possibility to control + certain aspects of the code generation. This is primarily done with the <emphasis> + <property moreinfo="none"><meta></property> + </emphasis> tag in the mapping files. The following section describes the possible <emphasis> + <property moreinfo="none"><meta></property> + </emphasis> tags and their use.</para> + + <section> + <title>The <literal moreinfo="none"><meta></literal> attribute</title> + + <para>The <emphasis> + <property moreinfo="none"><meta></property> + </emphasis> tag is a simple way of annotating the <emphasis> + <property moreinfo="none">hbm.xml</property> + </emphasis> with information, so tools have a natural place to store/read information that is + not directly related to the Hibernate core.</para> + + <para>You can use the <emphasis> + <property moreinfo="none"><meta></property> + </emphasis> tag to e.g. tell <emphasis> + <property moreinfo="none"><hbm2java></property> + </emphasis> to only generate <emphasis> + <property moreinfo="none">"protected"</property> + </emphasis> setters, have classes always implement a certain set of interfaces or even have + them extend a certain base class and even more.</para> + + <para>The following example shows how to use various <emphasis> + <property moreinfo="none"><meta></property> + </emphasis> attributes and the resulting java code.</para> + + <programlisting format="linespecific" role="XML"><![CDATA[<class name="Person"> + <meta attribute="class-description"> + Javadoc for the Person class + @author Frodo + </meta> + <meta attribute="implements">IAuditable</meta> + <id name="id" type="long"> + <meta attribute="scope-set">protected</meta> + <generator class="increment"/> + </id> + <property name="name" type="string"> + <meta attribute="field-description">The name of the person</meta> + </property> +</class>]]></programlisting> + + <para>The above <emphasis> + <property moreinfo="none">hbm.xml</property> + </emphasis> will produce something like the following (code shortened for better + understanding). Notice the Javadoc comment and the protected set methods:</para> + + <programlisting format="linespecific" role="JAVA"><![CDATA[// default package + +import java.io.Serializable; +import org.apache.commons.lang.builder.EqualsBuilder; +import org.apache.commons.lang.builder.HashCodeBuilder; +import org.apache.commons.lang.builder.ToStringBuilder; + +/** + * Javadoc for the Person class + * @author Frodo + */ +public class Person implements Serializable, IAuditable { + + public Long id; + + public String name; + + public Person(java.lang.String name) { + this.name = name; + } + + public Person() { + } + + public java.lang.Long getId() { + return this.id; + } + + protected void setId(java.lang.Long id) { + this.id = id; + } + + /** + * The name of the person + */ + public java.lang.String getName() { + return this.name; + } + + public void setName(java.lang.String name) { + this.name = name; + } + +}]]></programlisting> + + <table frame="topbot"> + <title>Supported meta tags</title> + + <tgroup cols="2"> + <colspec colwidth="1.0*"></colspec> + + <colspec colwidth="2*"></colspec> + + <thead> + <row> + <entry>Attribute</entry> + + <entry>Description</entry> + </row> + </thead> + + <tbody> + <row> + <entry> + <literal moreinfo="none">class-description</literal> + </entry> + + <entry>inserted into the javadoc for classes</entry> + </row> + + <row> + <entry> + <literal moreinfo="none">field-description</literal> + </entry> + + <entry>inserted into the javadoc for fields/properties</entry> + </row> + + <row> + <entry> + <literal moreinfo="none">interface</literal> + </entry> + + <entry>If true, an interface is generated instead of an class.</entry> + </row> + + <row> + <entry> + <literal moreinfo="none">implements</literal> + </entry> + + <entry>interface the class should implement</entry> + </row> + + <row> + <entry> + <literal moreinfo="none">extends</literal> + </entry> + + <entry>class that the current class should extend (ignored for subclasses)</entry> + </row> + + <row> + <entry> + <literal moreinfo="none">generated-class</literal> + </entry> + + <entry>overrule the name of the actual class generated</entry> + </row> + + <row> + <entry> + <literal moreinfo="none">scope-class</literal> + </entry> + + <entry>scope for class</entry> + </row> + + <row> + <entry> + <literal moreinfo="none">scope-set</literal> + </entry> + + <entry>scope for setter method</entry> + </row> + + <row> + <entry> + <literal moreinfo="none">scope-get</literal> + </entry> + + <entry>scope for getter method</entry> + </row> + + <row> + <entry> + <literal moreinfo="none">scope-field</literal> + </entry> + + <entry>scope for actual field</entry> + </row> + + <row> + <entry> + <literal moreinfo="none">default-value</literal> + </entry> + + <entry>default initialization value for a field</entry> + </row> + + <row> + <entry> + <literal moreinfo="none">use-in-tostring</literal> + </entry> + + <entry>include this property in the <literal moreinfo="none">toString()</literal></entry> + </row> + + <row> + <entry> + <literal moreinfo="none">use-in-equals</literal> + </entry> + + <entry>include this property in the <literal moreinfo="none">equals()</literal><diffmk:wrapper diffmk:change="changed"> and + </diffmk:wrapper><literal moreinfo="none">hashCode()</literal> method. If no use-in-equals is specified, no + equals/hashcode will be generated.</entry> + </row> + + <row> + <entry> + <literal moreinfo="none">gen-property</literal> + </entry> + + <entry>property will not be generated if false (use with care)</entry> + </row> + + <row> + <entry> + <literal moreinfo="none">property-type</literal> + </entry> + + <entry>Overrides the default type of property. Use this with any tag's to specify the + concrete type instead of just Object.</entry> + </row> + + <row> + <entry> + <literal moreinfo="none">class-code</literal> + </entry> + + <entry>Extra code that will inserted at the end of the class</entry> + </row> + + <row> + <entry> + <literal moreinfo="none">extra-import</literal> + </entry> + + <entry>Extra import that will inserted at the end of all other imports</entry> + </row> + </tbody> + </tgroup> + </table> + + <para>Attributes declared via the <emphasis> + <property moreinfo="none"><meta></property> + </emphasis> tag are per default <emphasis> + <property moreinfo="none">"inherited"</property> + </emphasis> inside an <emphasis> + <property moreinfo="none">hbm.xml</property> + </emphasis> file.</para> + + <para>What does that mean? It means that if you e.g want to have all your classes implement + <literal moreinfo="none">IAuditable</literal> then you just add an <emphasis> <meta + attribute="implements">IAuditable</meta></emphasis> in the top of the <emphasis> + <property moreinfo="none">hbm.xml</property> + </emphasis> file, just after <emphasis> + <property moreinfo="none"><hibernate-mapping></property>. </emphasis> Now all classes defined + in that <emphasis> + <property moreinfo="none">hbm.xml</property> + </emphasis> file will implement <literal moreinfo="none">IAuditable</literal>!</para> + + <note> + <title>Note:</title> + <para>This applies to <emphasis>all</emphasis> + <literal moreinfo="none"><meta></literal>-tags. Thus it can also e.g. be used to specify that + all fields should be declare protected, instead of the default private. This is done by + adding <literal moreinfo="none"><diffmk:wrapper diffmk:change="changed"><meta + attribute="scope-field">protected</meta></diffmk:wrapper></literal> at e.g. just under + the <literal moreinfo="none"><class></literal> tag and all fields of that class will be + protected.</para> + </note> + + <para>To avoid having a <emphasis> + <property moreinfo="none"><meta></property> + </emphasis> tag inherited then you can simply specify <emphasis> inherit = "false"</emphasis> + for the attribute, e.g. <emphasis> <meta attribute = "scope-class" inherit = + "false">public abstract</meta></emphasis> will restrict the <emphasis> + <property moreinfo="none">"class-scope"</property> + </emphasis> to the current class, not the subclasses.</para> + + <section> + <title>Recommendations</title> + + <para>The following are some good practices when using <emphasis> + <property moreinfo="none"><meta></property> + </emphasis> attributes.</para> + + <section> + <title>Dangers of a class level <literal moreinfo="none">use-in-string and use-in-equals</literal> meta + attributes when having bi-directional associations</title> + + <para>If we have two entities with a bi-directional association between them and define at + class scope level the meta attributes: <emphasis> + <property moreinfo="none">use-in-string</property>, </emphasis> + <emphasis> + <property moreinfo="none">use-in-equals</property>: </emphasis></para> + + <programlisting format="linespecific" role="XML"><![CDATA[<hibernate-mapping> + <class name="Person"> + <meta attribute="use-in-tostring">true</meta> + <meta attribute="use-in-equals">true</meta> + ... + </class> +</hibernate-mapping>]]></programlisting> + + <para>And for <emphasis> + <property moreinfo="none">Event.hbm</property> + </emphasis> file:</para> + + <programlisting format="linespecific" role="XML"><![CDATA[<hibernate-mapping> + <class name="events.Event" table="EVENTS"> + <meta attribute="use-in-tostring">true</meta> + <meta attribute="use-in-equals">true</meta> + <id name="id" column="EVENT_ID"> + <generator class="native"/> + </id> + <property name="date" type="timestamp" column="EVENT_DATE"/> + <property name="title"/> + <set name="participants" table="PERSON_EVENT" inverse="true"> + <key column="EVENT_ID"/> + <many-to-many column="PERSON_ID" class="events.Person"/> + </set> + </class> +</hibernate-mapping>]]></programlisting> + + <para>Then <emphasis> + <property moreinfo="none"><hbm2java></property> + </emphasis> will assume you want to include all properties and collections in the + <property moreinfo="none">toString()/equals()</property> methods and this can result in infinite + recursive calls.</para> + + <para>To remedy this you have to decide which side of the association will include the other + part (if at all) in the <property moreinfo="none">toString()/equals()</property> methods. Therefore it is + not a good practice to put at class scope such <emphasis> + <property moreinfo="none">meta</property> + </emphasis> attributes, unless you are defining a class without bi-directional + associations.</para> + + <para>We recomend instead to add the <emphasis> + <property moreinfo="none">meta</property> + </emphasis> attributes at the property level:</para> + + <programlisting format="linespecific" role="XML"><![CDATA[<hibernate-mapping> + <class name="events.Event" table="EVENTS"> + <id name="id" column="EVENT_ID"> + <meta attribute="use-in-tostring">true</meta> + <generator class="native"/> + </id> + <property name="date" type="timestamp" column="EVENT_DATE"/> + <property name="title"> + <meta attribute="use-in-tostring">true</meta> + <meta attribute="use-in-equals">true</meta> + </property> + <set name="participants" table="PERSON_EVENT" inverse="true"> + <key column="EVENT_ID"/> + <many-to-many column="PERSON_ID" class="events.Person"/> + </set> + </class> +</hibernate-mapping>]]></programlisting> + + <para>and now for <property moreinfo="none">Person</property>:</para> + + <programlisting format="linespecific" role="XML"><![CDATA[<hibernate-mapping> + <class name="Person"> + <meta attribute="class-description"> + Javadoc for the Person class + @author Frodo + </meta> + <meta attribute="implements">IAuditable</meta> + <id name="id" type="long"> + <meta attribute="scope-set">protected</meta> + <meta attribute="use-in-tostring">true</meta> + <generator class="increment"/> + </id> + <property name="name" type="string"> + <meta attribute="field-description">The name of the person</meta> + <meta attribute="use-in-tostring">true</meta> + </property> + </class> +</hibernate-mapping>]]></programlisting> + </section> + + <section> + <title>Be aware of putting at class scope level <literal moreinfo="none"><meta></literal> + attribute <literal moreinfo="none">use-in-equals</literal></title> + + <para>For <property moreinfo="none">equal()/hashCode()</property> method generation, you have to take into + account that the attributes that participate on such method definition, should take into + account only attributes with business meaning (the name, social security number, etc, but + no generated id's, for example).</para> + + <para>This is important because Java's hashbased collections, such as + <property moreinfo="none">java.util.Set</property> relies on <property moreinfo="none">equals()</property> and + <property moreinfo="none">hashcode()</property> to be correct and not change for objects in the set; + this can be a problem if the id gets assigned for an object after you inserted it into a + set.</para> + + <para>Therefore automatically configuration of the generation of + <property moreinfo="none">equals()/hashCode()</property> methods specifying at class scope level the <emphasis> + <property moreinfo="none"><meta></property> + </emphasis> attribute <emphasis> + <property moreinfo="none">use-in-equals</property> + </emphasis><diffmk:wrapper diffmk:change="changed"> could be a dangerous decision that could produce non expected + side-effect.</diffmk:wrapper></para> + + <para><ulink url="http://www.hibernate.org/109.html">Here</ulink> you can get more in-depth + explanation on the subject of <property moreinfo="none">equals()</property><diffmk:wrapper diffmk:change="changed"> and + </diffmk:wrapper><property moreinfo="none">hashcode()</property>.</para> + </section> + </section> + + <section> + <title>Advanced <meta> attribute examples</title> + + <para>This section shows an example for using meta attributes (including userspecific + attributes) together with the code generation features in <property moreinfo="none"><diffmk:wrapper diffmk:change="changed">Hibernate + Tools</diffmk:wrapper></property>.</para> + + <para>The usecase being implemented is to automatically insert some pre- and post-conditions + into the getter and setters of the generated POJO. </para> + + <section> + <title>Generate pre/post-conditions for methods</title> + + <para>With a <emphasis> <meta attribute="class-code"></emphasis>, you can add + additional methods on a given class, nevertheless such <emphasis> + <property moreinfo="none"><meta></property> + </emphasis> attribute can not be used at a property scope level and <property moreinfo="none">Hibernate + Tools</property> does not provide such <emphasis> + <property moreinfo="none"><meta></property> + </emphasis> attributes.</para> + + <para>A possible solution for this is to modify the freemarker templates responsible for + generating the POJO's. If you look inside <emphasis> + <property moreinfo="none">hibernate-tools.jar</property>, </emphasis> you can find the template: <emphasis> + <property moreinfo="none">pojo/PojoPropertyAccessor.ftl</property> + </emphasis></para> + + <para><diffmk:wrapper diffmk:change="changed">This file is as the name indicates used to generate property accessors for + pojo's.</diffmk:wrapper></para> + + <para>Extract the <emphasis> + <property moreinfo="none">PojoPropertyAccessor.ftl</property> + </emphasis> into a local folder i.e. <emphasis> + <property moreinfo="none">${hbm.template.path}</property>, </emphasis> respecting the whole path, for + example: <emphasis> + <property moreinfo="none">${hbm.template.path}/pojo/PojoPropertyAccessor.ftl</property> + </emphasis></para> + + <para>The contents of the file is something like this:</para> + + <programlisting format="linespecific" role="XML"><![CDATA[<#foreach property in pojo.getAllPropertiesIterator()> + ${pojo.getPropertyGetModifiers(property)} + ${pojo.getJavaTypeName(property, jdk5)} + ${pojo.getGetterSignature(property)}() { + return this.${property.name}; + } + + ${pojo.getPropertySetModifiers(property)} void set${pojo.getPropertyName(property)} + (${pojo.getJavaTypeName(property, jdk5)} ${property.name}) + { + this.${property.name} = ${property.name}; + } +</#foreach>]]></programlisting> + + <para>We can add conditionally pre/post-conditions on our <literal moreinfo="none">set</literal> method + generation just adding a little Freemarker syntax to the above source code:</para> + + <programlisting format="linespecific" role="XML"><![CDATA[<#foreach property in pojo.getAllPropertiesIterator()> + ${pojo.getPropertyGetModifiers(property)} + ${pojo.getJavaTypeName(property, jdk5)} + ${pojo.getGetterSignature(property)}() + { + return this.${property.name}; + } + + ${pojo.getPropertySetModifiers(property)} void set${pojo.getPropertyName(property)} + (${pojo.getJavaTypeName(property, jdk5)} ${property.name}) + { + <#if pojo.hasMetaAttribute(property, "pre-cond")> + ${c2j.getMetaAsString(property, "pre-cond","\n")} + </#if> + this.${property.name} = ${property.name}; + <#if pojo.hasMetaAttribute(property, "post-cond")> + ${c2j.getMetaAsString(property, "post-cond","\n")} + </#if> +} +</#foreach>]]> +</programlisting> + + <para>Now if in any <emphasis> + <property moreinfo="none">.hbm.xml</property> + </emphasis> file we define the <emphasis> + <property moreinfo="none"><meta></property> + </emphasis> attributes: <literal moreinfo="none">pre-cond</literal> or <literal moreinfo="none">post-cond</literal>, their + contents will be generated into the body of the relevant <literal moreinfo="none">set</literal><diffmk:wrapper diffmk:change="changed"> + method.</diffmk:wrapper></para> + + <para>As an example let us add a pre-condition for property <literal moreinfo="none">name</literal> + preventing no <property moreinfo="none">Person</property><diffmk:wrapper diffmk:change="changed"> can have an empty name. Hence we have to modify + the </diffmk:wrapper><emphasis> + <property moreinfo="none">Person.hbm.xml</property> + </emphasis> file like this:</para> + + <programlisting format="linespecific" role="XML"><![CDATA[<hibernate-mapping> + <class name="Person"> + <id name="id" type="long"> + <generator class="increment"/> + </id> + <property name="firstName" type="string"> + <meta attribute="pre-cond"> + if ((firstName != null) && (firstName.length() == 0) ) { + throw new IllegalArgumentException("firstName can not be an empty String"); + } + </meta> + </property> +</class> +</hibernate-mapping>]]></programlisting> + + <note> + <title>Note:</title> + <para>I) To escape the & symbol we put &amp;. You can use + <![CDATA[]]> instead.</para> + <para>II) Note that we are referring to "firstName" directly and this is the parameter + name not the actual field name. If you want to refer the field you have to use + "this.firstName" instead. </para> + </note> + + <para>Finally we have to generate the <emphasis> + <property moreinfo="none">Person.java</property> + </emphasis> class, for this we can use both Eclipse and Ant as long as you remember to set + or fill in the templatepath setting. For Ant we configure <emphasis> + <property moreinfo="none"><hibernatetool></property> + </emphasis> task via <literal moreinfo="none">the templatepath</literal> attribute as in:</para> + + <programlisting format="linespecific" role="XML"><![CDATA[ + <target name="hbm2java"> + <taskdef name="hibernatetool" + classname="org.hibernate.tool.ant.HibernateToolTask" + classpathref="lib.classpath"/> + <hibernatetool destdir="${hbm2java.dest.dir}" + templatepath="${hbm.template.path}"> + <classpath> + <path refid="pojo.classpath"/> + </classpath> + <configuration> + <fileset dir="${hbm2java.src.dir}"> + <include name="**/*.hbm.xml"/> + </fileset> + </configuration> + <hbm2java/> + </hibernatetool> + </target>]]></programlisting> + + <para>Invoking the target <emphasis> + <property moreinfo="none"><hbm2java></property> + </emphasis> will generate on the <emphasis> + <property moreinfo="none">${hbm2java.dest.dir}</property> + </emphasis> the file <emphasis> + <property moreinfo="none">Person.java</property> + </emphasis>:</para> + + <programlisting format="linespecific" role="JAVA"><![CDATA[// default package +import java.io.Serializable; +public class Person implements Serializable { + + public Long id; + + public String name; + + public Person(java.lang.String name) { + this.name = name; + } + + public Person() { + } + + public java.lang.Long getId() { + return this.id; + } + + public void setId(java.lang.Long id) { + this.id = id; + } + + public java.lang.String getName() { + return this.name; + } + + public void setName(java.lang.String name) { + if ((name != null) && (name.length() == 0)) { + throw new IllegalArgumentException("name can not be an empty String"); + } + this.name = name; + } + }]]></programlisting> + + <para><diffmk:wrapper diffmk:change="added">In conclusion, this document is intended to introduce you to Hibernate plugin specific + features related to tools bath for the Eclipse and Ant tasks.</diffmk:wrapper></para> + + <para><diffmk:wrapper diffmk:change="added">In the </diffmk:wrapper><link diffmk:change="added" linkend="plugins"><diffmk:wrapper diffmk:change="added">Eclipse Plugins</diffmk:wrapper></link><diffmk:wrapper diffmk:change="added"> chapter you've learnt + about a set of wizards for creating Mapping files, Configuration file, Console + Configuration, got familiar with Mapping and Configuration files editors, tooling for + organizing and controlling Reverse Engineering, Hibernate Console and Mapping diagram as + well.</diffmk:wrapper></para> + + <para diffmk:change="added"><diffmk:wrapper diffmk:change="added">The rest chapters have shown the aspects of using the </diffmk:wrapper><property moreinfo="none"><diffmk:wrapper diffmk:change="changed">Hibernate + Tools</diffmk:wrapper></property><diffmk:wrapper diffmk:change="added"> via Ant tasks.</diffmk:wrapper></para> + + <para diffmk:change="added"><diffmk:wrapper diffmk:change="added">Please, visit </diffmk:wrapper><ulink diffmk:change="added" url="http://www.jboss.com/index.html?module=bb&op=viewforum&f=201"><diffmk:wrapper diffmk:change="added">JBoss + Tools Users Forum</diffmk:wrapper></ulink><diffmk:wrapper diffmk:change="added"> to leave questions or/and suggestions on the topic. Your + feedback is always appreciated.</diffmk:wrapper></para> + </section> + </section> + + </section> + +</chapter> + + + + </book> Modified: branches/jbosstools-3.0.0.CR1/hibernatetools/docs/reference/en/modules/plugins.xml =================================================================== --- branches/jbosstools-3.0.0.CR1/hibernatetools/docs/reference/en/modules/plugins.xml 2008-12-19 19:41:47 UTC (rev 12777) +++ branches/jbosstools-3.0.0.CR1/hibernatetools/docs/reference/en/modules/plugins.xml 2008-12-19 19:47:46 UTC (rev 12778) @@ -27,7 +27,7 @@ </note> </section> - <section id="map_file_wizard" revisionflag="added"> + <section id="map_file_wizard"> <title>Creating a Hibernate Mapping File</title> <para>Hibernate mapping files are used to specify how your objects are related to database @@ -136,7 +136,7 @@ </emphasis> for the basis of a Console configuration.</para> </section> - <section id="console_conf" role="updated"> + <section id="console_conf" > <title>Creating a Hibernate Console Configuration</title> <para>A Console configuration describes how the <property>Hibernate plugin</property> should @@ -1235,7 +1235,7 @@ </section> </section> - <section id="map_config_struct_editor" revisionflag="added"> + <section id="map_config_struct_editor" > <title>Structured Hibernate Mapping and Configuration File Editor</title> <para>The structured editor represents the file in the tree form. It also allows to modify the structure of the file and its elements with the help of tables provided on the right-hand @@ -1566,7 +1566,7 @@ </section> </section> - <section revisionflag="changed"> + <section> <title>Prototyping Queries</title> <para>Queries can be prototyped by entering them in the <property>HQL</property> or @@ -1735,7 +1735,7 @@ </section> </section> - <section id="dali_integration" role="new"> + <section id="dali_integration"> <title>Hibernate support for Dali plugins in Eclipse WTP</title> <para>Starting from 3.0.0 Alpha1 version of <property>JBoss Tools</property> Hibernate plugins Modified: branches/jbosstools-3.0.0.CR1/hibernatetools/docs/reference/en/modules/reverseengineering.xml =================================================================== --- branches/jbosstools-3.0.0.CR1/hibernatetools/docs/reference/en/modules/reverseengineering.xml 2008-12-19 19:41:47 UTC (rev 12777) +++ branches/jbosstools-3.0.0.CR1/hibernatetools/docs/reference/en/modules/reverseengineering.xml 2008-12-19 19:47:46 UTC (rev 12778) @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="ISO-8859-1"?> -<chapter id="reverseengineering"> +<chapter id="reverseengineering" role="updated"> <title>Controlling reverse engineering</title> <para>When using the <emphasis> @@ -33,7 +33,7 @@ to a fully qualified classname.</para> </section> - <section id="hibernaterevengxmlfile"> + <section id="hibernaterevengxmlfile" role="updated"> <title>hibernate.reveng.xml file</title> <para>To have fine control over the process a <emphasis>

15 years, 4 months

1
0
0 / 0

JBoss Tools SVN: r12777 - in branches/jbosstools-3.0.0.CR1/struts/docs/struts_tools_tutorial/en: modules and 1 other directory.

by jbosstools-commits＠lists.jboss.org

Author: smukhina Date: 2008-12-19 14:41:47 -0500 (Fri, 19 Dec 2008) New Revision: 12777 Added: branches/jbosstools-3.0.0.CR1/struts/docs/struts_tools_tutorial/en/master_output.xml Modified: branches/jbosstools-3.0.0.CR1/struts/docs/struts_tools_tutorial/en/master.xml branches/jbosstools-3.0.0.CR1/struts/docs/struts_tools_tutorial/en/modules/relevant_resources.xml Log: https://jira.jboss.org/jira/browse/JBDS-324 the latest docs that are done for release 3.0.0.CR1 from trunk are added to branch master_output - the file to build guide versions with highlighted diff markers Modified: branches/jbosstools-3.0.0.CR1/struts/docs/struts_tools_tutorial/en/master.xml =================================================================== --- branches/jbosstools-3.0.0.CR1/struts/docs/struts_tools_tutorial/en/master.xml 2008-12-19 19:33:13 UTC (rev 12776) +++ branches/jbosstools-3.0.0.CR1/struts/docs/struts_tools_tutorial/en/master.xml 2008-12-19 19:41:47 UTC (rev 12777) @@ -41,7 +41,7 @@ </copyright> <releaseinfo> - Version: 3.0.0.beta1 + Version: 3.0.0.CR1 </releaseinfo> <abstract> <title/> Added: branches/jbosstools-3.0.0.CR1/struts/docs/struts_tools_tutorial/en/master_output.xml =================================================================== --- branches/jbosstools-3.0.0.CR1/struts/docs/struts_tools_tutorial/en/master_output.xml (rev 0) +++ branches/jbosstools-3.0.0.CR1/struts/docs/struts_tools_tutorial/en/master_output.xml 2008-12-19 19:41:47 UTC (rev 12777) @@ -0,0 +1,1340 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" +"http://www.docbook.org/xml/4.3/docbookx.dtd" + +[<!ENTITY introduction SYSTEM "modules/introduction.xml"> +<!ENTITY struts_application SYSTEM "modules/struts_application.xml"> +<!ENTITY generating_stub SYSTEM "modules/generating_stub.xml"> +<!ENTITY coding_files SYSTEM "modules/coding_files.xml"> +<!ENTITY compiling_and_running SYSTEM "modules/compiling_and_running.xml"> +<!ENTITY struts_validation SYSTEM "modules/struts_validation.xml"> +<!ENTITY relevant_resources SYSTEM "modules/relevant_resources.xml"> + +<!ENTITY seamlink "../../seam/html_single/index.html"> +<!ENTITY aslink "../../as/html_single/index.html"> +<!ENTITY esblink "../../esb_ref_guide/html_single/index.html"> +<!ENTITY gsglink "../../GettingStartedGuide/html_single/index.html"> +<!ENTITY hibernatelink "../../hibernatetools/html_single/index.html"> +<!ENTITY jbpmlink "../../jbpm/html_single/index.html"> +<!ENTITY jsflink "../../jsf/html_single/index.html"> +<!ENTITY jsfreflink "../../jsf_tools_ref_guide/html_single/index.html"> +<!ENTITY jsftutoriallink "../../jsf_tools_tutorial/html_single/index.html"> +<!ENTITY strutsreflink "../../struts_tools_ref_guide/html_single/index.html"> +<!ENTITY strutstutoriallink "../../struts_tools_tutorial/html_single/index.html"> + +]><book xmlns:diffmk="http://diffmk.sf.net/ns/diff"> + + <bookinfo> + <title>Struts Tools Tutorial</title> + + <author><firstname>Anatoly</firstname><surname>Fedosik</surname></author> + <author><firstname>Olga</firstname><surname>Chikvina</surname></author> + <author><firstname>Svetlana</firstname><surname>Mukhina</surname><email>smukhina(a)exadel.com</email></author> + + <pubdate>April 2008</pubdate> + <copyright> + <year>2007</year> + <year>2008</year> + <holder>JBoss, a division of Red Hat Inc.</holder> + </copyright> + + <releaseinfo><diffmk:wrapper diffmk:change="changed"> + Version: 3.0.0.CR1 + </diffmk:wrapper></releaseinfo> +<abstract> + <title></title> + <para> + <ulink url="http://download.jboss.org/jbosstools/nightly-docs/en/struts_tools_tutoria...">PDF version</ulink> + </para> +</abstract> + + + </bookinfo> + + <toc></toc> + + +<chapter id="introduction" xml:base="file:///home/ochikvina/WORK/for_compare/trunk/struts/docs/struts_tools_tutorial/en/modules/introduction.xml" xreflabel="introduction"> + <?dbhtml filename="introduction.html"?> + <chapterinfo> + <keywordset> + <keyword>JBoss Tools</keyword> + <keyword>Eclipse</keyword> + <keyword>Java</keyword> + <keyword>JBoss</keyword> + </keywordset> + </chapterinfo> + <title>Introduction</title> + <para>The following chapters describe how to deal with classic/old style of Struts development. We + recommend users to use <ulink url="../../seam/html_single/index.html">JBoss Seam</ulink> to + simplify development, but until then you can read about classical Struts usage here.</para> + + <para>We are going to show you how to create a simple <emphasis> + <property moreinfo="none">Struts application</property> + </emphasis> using the JBoss Tools. The completed application will ask a user to enter + a name and click a button. The resulting new page will display the familiar message, + "Hello <name>!"</para> + <para>This document will show you how to create such an application from the beginning, along the + way demonstrating some of the powerful features of JBoss Tools. With the help of our tutorial you will design the + application, generate stub code for the application, fill in the stub coding, compile the + application, and finally run it all from inside the Eclipse.</para> + + <section> + <title>Other relevant resources on the topic</title> + + <para>All JBoss Developer Studio/JBoss Tools documentation you can find <ulink url="http://docs.jboss.org/tools/">here</ulink>.</para> + <para>The latest documentation builds are available <ulink url="http://download.jboss.org/jbosstools/nightly-docs/">here</ulink>.</para> + + </section> + +</chapter> + + +<chapter id="struts_application" xml:base="file:///home/ochikvina/WORK/for_compare/trunk/struts/docs/struts_tools_tutorial/en/modules/struts_application.xml" xreflabel="struts_application"> + <?dbhtml filename="struts_application.html"?> + <chapterinfo> + <keywordset> + <keyword>JBoss Tools</keyword> + <keyword>Struts</keyword> + <keyword>Struts Application</keyword> + </keywordset> + </chapterinfo> + + <title>Creating a Simple Struts Application</title> + + <para>Firstly, we assume that you have already launched Eclipse with JBoss Tools installed and + also that the <property moreinfo="none">Web Development perspective</property> is the current perspective. (If not, make it + active by selecting <emphasis> + <property moreinfo="none">Window > Open Perspective > Other > Web + Development</property> + </emphasis> from the menu bar.)</para> + + <section id="StartingUp"> + <title>Starting Up</title> + <para>We are first going to create a new project for the application.</para> + <itemizedlist> + <listitem> + <para>Go to the menu bar and select <emphasis> + <property moreinfo="none">File > New > Project...</property> + </emphasis>.</para> + </listitem> + <listitem> + <para>Select <emphasis> + <property moreinfo="none">JBoss Tools Web > Struts > Struts Project</property> + </emphasis> in the New Project dialog box</para> + </listitem> + <listitem> + <para>Click <emphasis> + <property moreinfo="none">Next </property> + </emphasis></para> + </listitem> + <listitem> + <para>Enter "StrutsHello" as the project name</para> + </listitem> + <listitem> + <para>Leave everything else as is, and click <emphasis> + <property moreinfo="none">Next</property> + </emphasis></para> + </listitem> + <listitem> + <para>Click <emphasis> + <property moreinfo="none">Next</property> + </emphasis> again</para> + </listitem> + <listitem> + <para>Make sure that <emphasis> + <property moreinfo="none">struts-bean.tld</property> + </emphasis>, <emphasis> + <property moreinfo="none">struts-html.tld</property> + </emphasis>, and <emphasis> + <property moreinfo="none">struts-logic.tld</property> + </emphasis> are checked in the list of included tag libraries and then click <emphasis> + <property moreinfo="none">Finish</property> + </emphasis></para> + </listitem> + </itemizedlist> + <para>A "StrutsHello" node should appear in the upper-left Package + Explorer view.</para> + <itemizedlist> + <listitem> + <para>Click the plus sign next to <emphasis> + <property moreinfo="none">StrutsHello</property> + </emphasis> to reveal the child nodes</para> + </listitem> + <listitem> + <para>Click the plus sign next to <emphasis> + <property moreinfo="none">WebContent</property> + </emphasis> under StrutsHello</para> + </listitem> + <listitem> + <para>Click the plus sign next to <emphasis> + <property moreinfo="none">WEB-INF</property> + </emphasis> under WebContent</para> + </listitem> + <listitem> + <para>Then, double-click on the <emphasis> + <property moreinfo="none">struts-config.xml</property> + </emphasis> node to display a diagram of the Struts application configuration + file in the editing area</para> + </listitem> + </itemizedlist> + <para>At this point, its empty except for the background grid lines.</para> + </section> + + <section id="CreatingtheApplicationComponents"> + <?dbhtml filename="CreatingtheApplicationComponents.html"?> + <title>Creating the Application Components</title> + <para>Now, we will design the application by creating the individual components as + placeholders first. (We dont have to complete all of the details inside the components + until afterwards.)</para> + <section id="CreatingJSPPagePlaceholders"> + <title>Creating JSP Page Placeholders</title> + <para>Next, let's create and place two JSP pages. We will not write any code + for the files, but only create them as placeholders so that we can create links to + them in the diagram. We will write the code a little bit later.</para> + <section id="CreatingthePagePlaceholders"> + <title>Creating the Page Placeholders</title> + <itemizedlist> + <listitem> + <para>Bring the Web Projects view to the front of the Package Explorer view + by selecting the <emphasis> + <property moreinfo="none">Web Projects</property> + </emphasis> tab next to that tab.</para> + </listitem> + <listitem> + <para>Right-click the <emphasis> + <property moreinfo="none">StrutsHello > WEB-ROOT (WebContent)</property> + </emphasis> folder in the Web Projects view and select <emphasis> + <property moreinfo="none">New > Folder...</property> + </emphasis></para> + </listitem> + <listitem> + <para>Enter <emphasis> + <property moreinfo="none">pages</property> + </emphasis> for a folder name and click <emphasis> + <property moreinfo="none">Finish</property> + </emphasis></para> + </listitem> + + <listitem> + <para>We will keep our presentation files in this folder</para> + </listitem> + + <listitem> + <para>Right-click the pages folder and select <emphasis> + <property moreinfo="none">New > Fila > JSP...</property> + </emphasis> + </para> + </listitem> + <listitem> + <para>For Name type in <emphasis> + <property moreinfo="none">inputname</property> + </emphasis> (the JSP extension will be automatically added to the file), + for Template select <emphasis> + <property moreinfo="none">StrutsForm</property> + </emphasis> and then click on the <emphasis> + <property moreinfo="none">Finish</property> + </emphasis> button</para> + </listitem> + <listitem> + <para>Right-click the pages folder again and select <emphasis> + <property moreinfo="none">New > File > JSP...</property> + </emphasis></para> + </listitem> + <listitem> + <para>For Name type in <emphasis> + <property moreinfo="none">greeting</property> + </emphasis>, for Template leave as Blank, and then click on the <emphasis> + <property moreinfo="none">Finish</property> + </emphasis> button</para> + </listitem> + </itemizedlist> + <para>Just leave these files as is for now.</para> + </section> + <section id="PlacingthePagePlaceholders"> + <title>Placing the Page Placeholders</title> + <para>Lets now place the two pages just created on the diagram.</para> + <itemizedlist> + <listitem> + <para>Click on the <emphasis> + <property moreinfo="none">struts-config.xml</property> + </emphasis> tab in the Editing area to bring the diagram to the + front</para> + </listitem> + <listitem> + <para>Click on the <emphasis> + <property moreinfo="none">inputname.jsp</property> + </emphasis> page in the Web Projects view, drag it onto the diagram, and + drop it</para> + </listitem> + <listitem><para>Click on the <emphasis> + <property moreinfo="none">greeting.jsp</property> + </emphasis> page in the Web Projects view, drag it onto the diagram, and + drop it to the right of the <emphasis> + <property moreinfo="none">/pages/inputname.jsp</property> + </emphasis> icon with some extra space</para></listitem> + </itemizedlist> + <para>You should now have two JSP pages in the diagram.</para> + </section> + </section> + <section id="CreatinganActionMappings"> + <title>Creating an Action Mappings</title> + <para>Using a context menu on the diagram, we are next going to create an Action + mapping.</para> + <itemizedlist> + <listitem> + <para>Right-click between the two icons and select <emphasis> + <property moreinfo="none">Add > Action</property> + </emphasis></para> + </listitem> + <listitem> + <para>Enter the following values:</para> + </listitem> + </itemizedlist> + <table> + <title>Action values</title> + <tgroup cols="2"> + <tbody> + <row> + <entry>path</entry> + <entry>/greeting</entry> + </row> + <row> + <entry>name</entry> + <entry>GetNameForm</entry> + </row> + <row> + <entry>scope</entry> + <entry>request</entry> + </row> + <row> + <entry>type</entry> + <entry>sample.GreetingAction</entry> + </row> + <row> + <entry>validate</entry> + <entry><leave blank></entry> + </row> + </tbody> + </tgroup> + </table> + <para>("GetNameForm" is the name for a form bean that we will create + later.)</para> + <itemizedlist> + <listitem> + <para>Click <emphasis> + <property moreinfo="none">Finish</property> + </emphasis></para> + </listitem> + </itemizedlist> + + <para>The <emphasis> + <property moreinfo="none">/greeting</property> + </emphasis> action should appear in four places, in the diagram, under the + action-mappings node, under the struts-config.xml node in Tree view, in Web Projects + view and in the Outline view. Also, note the asterisk to the right of the name, + struts-config.xml, in the Outline view showing that the file has been changed, but + not saved to disk.</para> + </section> + <section id="CreatingaLink"> + <title>Creating a Link</title> + <para>Let's now create a link from the inputname.jsp page to the action.</para> + <itemizedlist> + <listitem> + <para>On the left-hand side of the diagram in the column of icons, click on this + icon:</para> + </listitem> + </itemizedlist> + <figure float="0"> + <title>Create New Connection Icon</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts_application/struts_application_1.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + <itemizedlist> + <listitem> + <para>In the connect-the-components mode you are in now, click on the <emphasis> + <property moreinfo="none">/pages/inputname.jsp</property> + </emphasis> icon in the diagram and then click on the <emphasis> + <property moreinfo="none">/greeting</property> + </emphasis> action</para> + </listitem> + </itemizedlist> + <para>A link will be created from the page to the action.</para> + </section> + <section id="CreatingaForward"> + <title>Creating a Forward</title> + <para>Next, we are going to create a forward for the action.</para> + <itemizedlist> + <listitem> + <para>On the left-hand side of the diagram in the column of icons, click on this + icon, again:</para> + </listitem> + </itemizedlist> + <figure float="0"> + <title>Create New Connection Icon</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts_application/struts_application_1.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + <itemizedlist> + <listitem> + <para>Click on the <emphasis> + <property moreinfo="none">/greeting</property> + </emphasis> action icon in the diagram and then click on the <emphasis> + <property moreinfo="none">pages/greeting.jsp</property> + </emphasis> icon</para> + </listitem> + <listitem> + <para>That's it. A link will be drawn from the actions new greeting + forward to the greeting.jsp JSP page. Note that the forwards name will be + set based on the name of the target JSP file name. If you don't + like it, you can easily change it</para> + </listitem> + <listitem> + <para>Select the <emphasis> + <property moreinfo="none">Tree</property> + </emphasis> tab at the bottom of the editor window (between Diagram and + Source)</para> + </listitem> + <listitem> + <para>Expand the <emphasis> + <property moreinfo="none">struts-config.xml/action-mappings//greeting</property> + </emphasis> node and then select the greeting forward</para> + </listitem> + <listitem> + <para>In the Properties Editor to the right, change the text to + "sayHello" in the Name field</para> + </listitem> + <listitem> + <para>Select the <emphasis> + <property moreinfo="none">Diagram</property> + </emphasis> tab at the bottom of the editor window and see how the diagram + is also updated to reflect the change</para> + </listitem> + </itemizedlist> + </section> + <section id="CreatingaGlobalForward"> + <title>Creating a Global Forward</title> + <para>One last component that we need to create in the diagram is a global forward.</para> + <itemizedlist> + <listitem> + <para>Somewhere in the top-left corner of diagram, right-click and select <emphasis> + <property moreinfo="none"> Add > Global Forward...</property> + </emphasis></para> + </listitem> + <listitem> + <para>Enter <emphasis> + <property moreinfo="none">getName</property> + </emphasis> in the Name field</para> + </listitem> + <listitem> + <para>Select the <emphasis> + <property moreinfo="none">Change...</property> + </emphasis>button for Path</para> + </listitem> + <listitem> + <para>In the Edit Path window, switch to the <emphasis> + <property moreinfo="none">Pages</property> + </emphasis> tab</para> + </listitem> + <listitem> + <para>Expand the <emphasis> + <property moreinfo="none">StrutsHello > WEB-ROOT (WebContent) > pages</property> + </emphasis> node and then select the inputname.jsp page</para> + </listitem> + <listitem> + <para>Click <emphasis> + <property moreinfo="none">Ok</property> + </emphasis>.</para> + </listitem> + <listitem> + <para>Leave the rest of the fields blank and click <emphasis> + <property moreinfo="none">OK</property> + </emphasis></para> + </listitem> + </itemizedlist> + <para>A forward object now appears on the diagram and also in the global-forwards folder + in the Outline view.</para> + <itemizedlist> + <listitem> + <para>Tidy up the diagram, by clicking and dragging around each icon, so that + the diagram looks something like this:</para> + </listitem> + </itemizedlist> + <figure float="0"> + <title>Diagram View</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts_application/struts_application_2.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + </section> + <section id="CreatingaFormBean"> + <title>Creating a Form Bean</title> + <para>One last thing that we need to do is to create a form bean.</para> + <itemizedlist> + <listitem> + <para>Switch to the Tree viewer in the editor for the struts-config.xml file, by + selecting the <emphasis> + <property moreinfo="none">Tree</property> + </emphasis> tab at the bottom of the editor window</para> + </listitem> + <listitem> + <para>Right-click <emphasis> + <property moreinfo="none">struts-config.xml > form-beans</property> + </emphasis> and select Create Form Bean</para> + </listitem> + <listitem> + <para>Enter <emphasis> + <property moreinfo="none">GetNameForm</property> + </emphasis> in the name field and <emphasis> + <property moreinfo="none">sample.GetNameForm</property> + </emphasis> for type</para> + </listitem> + <listitem> + <para>Click <emphasis> + <property moreinfo="none">Finish</property> + </emphasis></para> + </listitem> + <listitem> + <para>To save your changes to struts-config.xml, select <emphasis> + <property moreinfo="none">File > Save</property> + </emphasis> from the menu bar</para> + </listitem> + </itemizedlist> + <para>Note the disappearance of the asterisk next to the name, struts-config.xml.</para> + </section> + </section> +</chapter> + +<chapter id="generating_stub" xml:base="file:///home/ochikvina/WORK/for_compare/trunk/struts/docs/struts_tools_tutorial/en/modules/generating_stub.xml" xreflabel="generating_stub"> + <?dbhtml filename="generating_stub.html"?> + <chapterinfo> + <keywordset> + <keyword>JBoss Tools</keyword> + <keyword>Struts</keyword> + <keyword>Struts Application</keyword> + </keywordset> + </chapterinfo> + + <title>Generating Stub Coding</title> + <para>We are done with designing the application through the diagram. Now we need to write + code for the action component. We also need to write an action class for the <emphasis> + <property moreinfo="none">/greeting</property> + </emphasis> mapping along with a FormBean. To aid in the coding phase, JBoss Developer + Studio can generate Java class stubs for all of the components shown in the diagram.</para> + <itemizedlist> + <listitem> + <para>Switch back to the diagram, by selecting the <emphasis> + <property moreinfo="none">Diagram</property> + </emphasis> tab at the bottom of the editor window</para> + </listitem> + <listitem> + <para>Right-click a blank space in the diagram and select <emphasis> + <property moreinfo="none">Generate Java Code</property> + </emphasis></para> + </listitem> + <listitem> + <para>Leave everything as is in the dialog box and click <emphasis> + <property moreinfo="none">Generate</property> + </emphasis></para> + </listitem> + </itemizedlist> + <para>You should see a screen that says:</para> + <para>Generated classes: 2</para> + <para>Actions: 1</para> + <para>Form beans: 1</para> + <itemizedlist> + <listitem> + <para>Click <emphasis> + <property moreinfo="none">Finish</property> + </emphasis></para> + </listitem> + </itemizedlist> + <para>The Java files will be generated in a <emphasis> + <property moreinfo="none">JavaSource > sample</property> + </emphasis> folder that you can see in the Package Explorer view under the + "StrutsHello" node. One Action stub and one FormBean stub will have + been generated.</para> + </chapter> + +<chapter id="coding_files" xml:base="file:///home/ochikvina/WORK/for_compare/trunk/struts/docs/struts_tools_tutorial/en/modules/coding_files.xml" xreflabel="coding_files"> + <?dbhtml filename="coding_files.html"?> + <chapterinfo> + <keywordset> + <keyword>JBoss Tools</keyword> + <keyword>Struts</keyword> + <keyword>Struts Application</keyword> + </keywordset> + </chapterinfo> + + <title>Coding the Various Files</title> + <para>We will now code both the Java stub classes just generated, the JSP files left in as + placeholders from previous steps, and a new start JSP page we will have to create.</para> + <section id="JavaStubClasses"> + <title>Java Stub Classes</title> + <itemizedlist> + <listitem> + <para>To finish the two Java classes, switch to the <emphasis> + <property moreinfo="none">Package Explorer</property> + </emphasis> view and expand the <emphasis> + <property moreinfo="none">JavaSource > sample</property> + </emphasis> folder</para> + </listitem> + </itemizedlist> + <section id="GetNameForm.java"> + <title>GetNameForm.java</title> + <itemizedlist> + <listitem> + <para>Double-click <emphasis> + <property moreinfo="none">GetNameForm.java</property> + </emphasis> for editing</para> + </listitem> + + <listitem> + <para>You are looking at a Java stub class that was generated by JBoss + Developer Studio. Now we are going to edit the file</para> + </listitem> + + <listitem> + <para>Add the following attributes at the beginning of the class:</para> + </listitem> + </itemizedlist> + <programlisting format="linespecific" role="JAVA"><![CDATA[private String name = ""; + private String greetName = ""; +]]></programlisting> + + <itemizedlist> + <listitem> + <para>Inside the reset method, delete the TO DO and throw lines and + add:</para> + </listitem> + </itemizedlist> + <programlisting format="linespecific" role="JAVA"><![CDATA[this.name = ""; + this.greetName = ""; +]]></programlisting> + + <itemizedlist> + <listitem> + <para>Inside the validate method, delete the TO DO and throw lines and + add:</para> + </listitem> + </itemizedlist> + <programlisting format="linespecific" role="JAVA"><![CDATA[ActionErrors errors = new ActionErrors(); + return errors; +]]></programlisting> + + <itemizedlist> + <listitem> + <para>Right-click and select <emphasis> + <property moreinfo="none">Source > Generate Getters and Setters...</property> + </emphasis>from the context menu</para> + </listitem> + <listitem> + <para>In the dialog box, check the check boxes for name and greetName, + select First method for Insertion point, and click on the <emphasis> + <property moreinfo="none">OK</property> + </emphasis> button</para> + </listitem> + </itemizedlist> + <para>The final GetNameForm.java file should look like this:</para> + <programlisting format="linespecific" role="JAVA"><![CDATA[package sample; +import javax.servlet.http.HttpServletRequest; +import org.apache.struts.action.ActionErrors; +import org.apache.struts.action.ActionMapping; + +public class GetNameForm extends org.apache.struts.action.ActionForm +{ + + private String name = ""; + private String greetName = ""; + + public String getName() + { + return name; + } + public void setName(String name) + { + this.name = name; + } + + public String getGreetName() + { + return greetName; + } + + public void setGreetName(String greetName) + { + this.greetName = greetName; + } + + public GetNameForm() + { + } + + public void reset(ActionMapping actionMapping, HttpServletRequest request) + { + this.name = ""; + this.greetName = ""; + } + + public ActionErrors validate(ActionMapping actionMapping, + HttpServletRequest request) + { + ActionErrors errors = new ActionErrors(); + return errors; + } +} +]]></programlisting> + + <itemizedlist> + <listitem> + <para>Save the file</para> + </listitem> + </itemizedlist> + </section> + <section id="GreetingAction.java"> + <title>GreetingAction.java</title> + <itemizedlist> + <listitem> + <para>Open GreetingAction.java for editing</para> + </listitem> + <listitem> + <para>Inside the execute method, delete the TO DO lines and add the + following:</para> + </listitem> + </itemizedlist> + + <programlisting format="linespecific" role="JAVA"><![CDATA[String name = ((GetNameForm)form).getName(); +String greeting = "Hello, "+name+"!"; +((GetNameForm)form).setName(greeting); +return mapping.findForward(FORWARD_sayHello); +]]></programlisting> + + <para>The final version of GreetingAction.java should look like this:</para> + + <programlisting format="linespecific" role="JAVA"><![CDATA[package sample; +import javax.servlet.http.HttpServletRequest; +import javax.servlet.http.HttpServletResponse; +import org.apache.struts.action.ActionForm; +import org.apache.struts.action.ActionForward; +import org.apache.struts.action.ActionMapping; + +public class GreetingAction extends org.apache.struts.action.Action +{ + + // Global Forwards + public static final String GLOBAL_FORWARD_getName = "getName"; + + // Local Forwards + public static final String FORWARD_sayHello = "sayHello"; + + public GreetingAction() + { + } + public ActionForward execute(ActionMapping mapping, ActionForm form, + HttpServletRequest request, HttpServletResponse response) throws Exception + { + String name = ((GetNameForm)form).getName(); + String greeting = "Hello, "+name+"!"; + ((GetNameForm)form).setName(greeting); + return mapping.findForward(FORWARD_sayHello); + } +} +]]></programlisting> + <itemizedlist> + <listitem> + <para>Save the file</para> + </listitem> + <listitem> + <para>Close the editors for the two Java files</para> + </listitem> + </itemizedlist> + <para>The last thing left to do is to code the JSP files whose editors should still + be open from having been created as placeholders.</para> + </section> + </section> + <section id="JSPPages"> + <title>JSP Pages</title> + <section id="inputname.jsp"> + <title>inputname.jsp</title> + <para>In this page, the user will enter any name and click the <emphasis> + <property moreinfo="none">submit</property> + </emphasis> button. Then, the greeting action will be called through the form.</para> + <itemizedlist> + <listitem> + <para>Click on the <emphasis> + <property moreinfo="none">inputname.jsp</property> + </emphasis> tab in the Editing area to bring its editor forward</para> + </listitem> + <listitem> + <para>In the Web Projects view, expand <emphasis> + <property moreinfo="none">StrutsHello > Configuration > default + > struts-config.xml > action-mappings</property> + </emphasis> and select <emphasis> + <property moreinfo="none">/greeting</property> + </emphasis></para> + </listitem> + <listitem> + <para>Drag it and drop it between the quotes for the <emphasis role="italic"> + <property moreinfo="none">"action"</property> + </emphasis> attribute to the <emphasis role="bold"> + <property moreinfo="none"><html:form></property> + </emphasis> element in the Source pane of the editor</para> + </listitem> + <listitem> + <para>Then type this text on a new line just below this line:</para> + <programlisting format="linespecific" role="XML"><![CDATA[Input name: + ]]></programlisting> + </listitem> + + <listitem> + <para>Select the <emphasis> + <property moreinfo="none">Visual</property> + </emphasis> pane of the editor</para> + </listitem> + <listitem> + <para>Then, in the JBoss Tools Palette, expand the <emphasis> + <property moreinfo="none">Struts Form</property> + </emphasis> library, select <emphasis> + <property moreinfo="none">text</property> + </emphasis>, and drag it onto the box + <note> + <title>Note:</title> + <para>By default there are only four groups on the JBoss Tools + Palette. If you wish to make some group visible click the <emphasis> + <property moreinfo="none">Show/Hide</property> + </emphasis> button on the top of palette and in the prompted + dialog check the group (or groups) you want to be shown.</para> + </note> + </para> + </listitem> + </itemizedlist> + <figure float="0"> + <title>JBoss Tools Palette</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts_application/struts_application_3.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + <itemizedlist> + <listitem> + <para>In the Insert Tag dialog box, type in name for property and select <emphasis> + <property moreinfo="none">Finish</property> + </emphasis></para> + </listitem> + <listitem> + <para>In the StrutsForm library in the JBoss Tools Palette, select <emphasis> + <property moreinfo="none">submit</property> + </emphasis>, and drag it to right after the text box in the Visual pane + of the editor</para> + </listitem> + <listitem> + <para>Right-click the <emphasis> + <property moreinfo="none">submit</property> + </emphasis> button and select <emphasis role="bold"> + <property moreinfo="none"><html:submit></property> + </emphasis> Attributes from the context menu</para> + </listitem> + <listitem> + <para>In the Attributes dialog box, select the <emphasis> + <property moreinfo="none">value</property> + </emphasis> field and type in "Say Hello!" for its + value</para> + </listitem> + </itemizedlist> + <para>After tidying the page source, the Editor window for the file should look + something like this:</para> + <figure float="0"> + <title>Editor Window</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts_application/struts_application_4.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + </section> + <section id="greeting.jsp"> + <title>greeting.jsp</title> + <para>Next, we will fill in the result page.</para> + <itemizedlist> + <listitem> + <para>Click on the <emphasis> + <property moreinfo="none">greeting.jsp</property> + </emphasis> tab in the Editing area to bring its editor forward</para> + </listitem> + <listitem> + <para>Type in the following code:</para> + </listitem> + </itemizedlist> + <programlisting format="linespecific" role="XML"><![CDATA[<html> +<head> + <title>Greeting</title> +</head> + <body> + <p> + </p> + </body> +</html> +]]></programlisting> + + <para>To complete editing of this file, we will use macros from the JBoss Tools + Palette. This palette is a view that should be available to the right of the + editing area.</para> + <itemizedlist> + <listitem> + <para>Click on the <emphasis> + <property moreinfo="none">Struts Common</property> + </emphasis> folder in the JBoss Tools Palette to open it</para> + </listitem> + <listitem> + <para>Position the cursor at the beginning of the greeting.jsp file in the + Source pane and then click on bean taglib in the JBoss Tools + Palette</para> + </listitem> + </itemizedlist> + <para>This will insert the following line at the top of the file:</para> + <programlisting format="linespecific" role="JAVA"><![CDATA[ +<%@ taglib uri="/WEB-INF/struts-bean.tld" prefix="bean" %> +]]></programlisting> + <itemizedlist> + <listitem> + <para>Click on the <emphasis> + <property moreinfo="none">Struts Bean</property> + </emphasis> folder in the JBoss Tools Palette to open it</para> + </listitem> + <listitem> + <para>Position the cursor inside the <emphasis role="bold"> + <property moreinfo="none"><p></property> + </emphasis> element</para> + </listitem> + <listitem> + <para>Click on write in the JBoss Tools Palette</para> + </listitem> + <listitem> + <para>Type in "GetNameForm" for the <emphasis role="italic"> + <property moreinfo="none">"name"</property> + </emphasis> attribute and add a <emphasis role="italic"> + <property moreinfo="none">"property"</property> + </emphasis> attribute with "greetName" as its + value</para> + </listitem> + </itemizedlist> + <para>The editor should now look like this:</para> + <figure float="0"> + <title>Editor Window</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts_application/struts_application_5.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + </section> + <section id="index.jsp"> + <title>index.jsp</title> + <para>Finally, we will need to create and edit an index.jsp page. This page will use + a Struts forward to simply redirect us to the getName global forward.</para> + <itemizedlist> + <listitem> + <para>In the Web Projects view, right-click on <emphasis> + <property moreinfo="none">StrutsHello > WEB-ROOT(WebContent)</property> + </emphasis> node and select <emphasis> + <property moreinfo="none">New > File > JSP..</property> + </emphasis></para> + </listitem> + <listitem> + <para>Type index for Name and click on the <emphasis> + <property moreinfo="none">Finish</property> + </emphasis> button</para> + </listitem> + <listitem> + <para>On the JBoss Tools Palette, select the <emphasis> + <property moreinfo="none">Struts Common</property> + </emphasis> folder of macros by clicking on it in the palette</para> + </listitem> + <listitem> + <para>Click on the logic taglib icon</para> + </listitem> + <listitem> + <para>Press the <emphasis> + <property moreinfo="none">Enter</property> + </emphasis> key in the editor to go to the next line</para> + </listitem> + <listitem> + <para>Back on the palette, select the <emphasis> + <property moreinfo="none">Struts Logic</property> + </emphasis> folder of macros</para> + </listitem> + <listitem> + <para>Click on redirect</para> + </listitem> + <listitem> + <para>Delete the ending tag, put a forward slash in front of the closing + angle bracket, and type "forward=getName" in front of + the slash</para> + </listitem> + </itemizedlist> + <para>The finished code for the page is shown below:</para> + <programlisting format="linespecific" role="JAVA"><![CDATA[<%@ taglib uri="/WEB-INF/struts-logic.tld" prefix="logic" %> +<logic:redirect forward="getName"/> +]]></programlisting> + <itemizedlist> + <listitem> + <para>To save all the edits to files, select <emphasis> + <property moreinfo="none">File>Save All</property> + </emphasis> from the menu bar</para> + </listitem> + </itemizedlist> + </section> + </section> + </chapter> + +<chapter id="compiling_and_running" xml:base="file:///home/ochikvina/WORK/for_compare/trunk/struts/docs/struts_tools_tutorial/en/modules/compiling_and_running.xml" xreflabel="compiling_and_running"> + <?dbhtml filename="compiling_and_running.html"?> + <chapterinfo> + <keywordset> + <keyword>JBoss Tools</keyword> + <keyword>Struts</keyword> + <keyword>Struts Application</keyword> + </keywordset> + </chapterinfo> + + <title>Compiling the Classes and Running the Application</title> + + <para>As this is the Eclipse environment, no explicit compilation step is required. By + default, Eclipse compiles as you go.</para> + + <para>Thus at this point everything is ready for running our application without having to leave JBoss + Developer Studio by using the JBoss Application Server engine that comes with the JBoss + Developer Studio. For controlling JBoss AS within JBoss Developer Studio, there is JBoss + Server view.</para> + <figure float="0"> + <title>JBoss Server Panel</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts_application/struts_application_6.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + <itemizedlist> + <listitem> + <para>Start up JBoss AS by clicking on the icon in JBoss Server view. (If JBoss AS + is already running, stop it by clicking on the red icon and then start it again. + Remember, the Struts run-time requires restarting the servlet engine when any + changes have been made.)</para> + </listitem> + <listitem> + <para>After the messages in the Console tabbed view stop scrolling, JBoss AS is + available. At this point, right-click on the getName global forward in the + struts-config.xml diagram view and select Run on Server.</para> + </listitem> + </itemizedlist> + <para>The browser should appear with the application started.</para> + </chapter> + +<chapter id="struts_validation" xml:base="file:///home/ochikvina/WORK/for_compare/trunk/struts/docs/struts_tools_tutorial/en/modules/struts_validation.xml" xreflabel="struts_validation"> + <?dbhtml filename="struts_validation.html"?> + <chapterinfo> + <keywordset> + <keyword>JBoss Developer Studio</keyword> + <keyword>Struts</keyword> + <keyword>Struts Validation</keyword> + </keywordset> + </chapterinfo> +<title>Struts Validation Examples</title> + +<para><property moreinfo="none">Validation</property> of input is an important part of any Web application. All Apache Jakarta frameworks, +including Struts, can use a common Jakarta Validation Framework for streamlining this aspect of Web +application development. The Validation Framework allows you to define validation rules and then apply these rules on the client-side or the server-side.</para> + + <para>JBoss Developer Studio makes using the <property moreinfo="none">Validation Framework</property> in Struts even easier with the help of a specialized editor for the XML files that controls validation in a project. In this document, we'll show you how this all works by creating some simple client-side validation and server-side validation examples.</para> + +<section id="StartingPoint"> +<?dbhtml filename="StartingPoint.html"?> +<title>Starting Point</title> +<para>The example assumes that you have already created our sample "StrutsHello" application from the +Getting Started Guide for Creating a Struts Application. You should have the JBoss Developer Studio perspective + open on this StrutsHello project.</para> +</section> + +<section id="DefiningTheValidationRule"> +<?dbhtml filename="DefiningTheValidationRule.html"?> +<title>Defining the Validation Rule</title> +<para>In these steps you will set up the validation that can be used for either client-side or +server side validation. You need to enable validation as a part of the project, define an error message, and tie it into an appropriate part of the application.</para> + +<itemizedlist> +<listitem><para>Right-click on a "plug-ins" node under the <emphasis><property moreinfo="none">StrutsHello > Configuration > default > struts-config.xml</property></emphasis> node in the Web Projects view and select <emphasis><property moreinfo="none">Create Special Plugin > Validators</property></emphasis> from the context menu</para></listitem> +<listitem><para>Further down in the Web Projects view, right-click on the +<emphasis><property moreinfo="none">StrutsHello > ResourceBundles</property></emphasis> node and select <emphasis><property moreinfo="none"> New > Properties File...</property></emphasis>from the context menu</para></listitem> +<listitem><para>In the dialog box, click on the <emphasis><property moreinfo="none">Browse...</property></emphasis>button next to the Folder field, expand the + JavaSource folder in this next dialog box, select the sample subfolder, and click on the <emphasis><property moreinfo="none">OK</property></emphasis> button</para></listitem> + <listitem><para>Back in the first dialog box, type in "applResources" for the Name field and click on the <emphasis><property moreinfo="none">Finish</property></emphasis> button</para></listitem> +<listitem><para>Right-click on a newly created file and select <emphasis><property moreinfo="none">Add > Default Error Messages</property></emphasis> + from the context menu</para></listitem> + +<listitem><para>Drag up the sample.applResources icon until you can drop it on the resources folder under struts-config.xml</para></listitem> +<listitem><para>Select<emphasis><property moreinfo="none"> File > Save </property></emphasis>All from the menu bar</para></listitem> +<listitem><para>Select validation.xml under the <emphasis><property moreinfo="none">StrutsHello > Validation</property></emphasis> node and double-click it to open it with the JBoss Tools XML Editor</para></listitem> +<listitem><para>Here you must create a Formset.</para></listitem> +<listitem><para>In the validation.xml file editor click the button <emphasis><property moreinfo="none">Create Formset</property></emphasis> on the panel <emphasis><property moreinfo="none">Formsets</property></emphasis></para></listitem> +<listitem><para>In the dialog <emphasis><property moreinfo="none">Add Formset</property></emphasis> fill the fields <emphasis><property moreinfo="none">Language</property></emphasis> and <emphasis><property moreinfo="none">Country</property></emphasis> or just leave them empty to create a default formset. Click <emphasis><property moreinfo="none">OK</property></emphasis></para></listitem> +</itemizedlist> +<figure float="0"> + <title>Create Formset</title> +<mediaobject> + <imageobject> + <imagedata fileref="images/struts_validation/struts_validation.png"></imagedata> + </imageobject> +</mediaobject> +</figure> +<itemizedlist> +<listitem><para>Expand the "form-beans" node under the <emphasis><property moreinfo="none">StrutsHello > Configuration > default > struts-config.xml node.</property></emphasis> Then, drag the form bean "GetNameForm" and drop it onto a formset in the <property moreinfo="none">XML</property> Editor</para></listitem> +<listitem><para>In the Validation Editor, expand the formset node, right-click GetNameForm, and select <emphasis><property moreinfo="none">Create Field...</property></emphasis> from the context menu</para></listitem> +<listitem><para>Enter a name for Property in the dialog box. A new property will be created:</para></listitem> +</itemizedlist> +<figure float="0"> + <title>New Property Is Added</title> +<mediaobject> + <imageobject> + <imagedata fileref="images/struts_validation/struts_validation_2.png"></imagedata> + </imageobject> +</mediaobject> +</figure> +<itemizedlist> +<listitem><para>In the Properties view for the name field to the right of the "tree" for the validation.xml file, click on the <emphasis><property moreinfo="none">Change...</property></emphasis>button next to the Depends entry field</para></listitem> +<listitem><para>In the displayed double list, select <emphasis><property moreinfo="none">required</property></emphasis> from the left list and then click <emphasis><property moreinfo="none">Add</property></emphasis></para></listitem> + <listitem><para>Click <emphasis><property moreinfo="none">Ok</property></emphasis></para></listitem> +<listitem><para>Right-click name and select <emphasis><property moreinfo="none">Add Arg...</property></emphasis> from the context menu</para></listitem> +<listitem><para>In the Add Arg dialog box, click on the <emphasis><property moreinfo="none">Change...</property></emphasis>button next to the <emphasis><property moreinfo="none">Key</property></emphasis> field</para></listitem> + <listitem><para>In the Key dialog box that appears now, click on the <emphasis><property moreinfo="none">Add</property></emphasis> button</para></listitem> + <listitem><para>Enter "name.required" in the Name field, and enter a person's name in the Value field</para></listitem> + <listitem><para>Click <emphasis><property moreinfo="none">Finish</property></emphasis>, then <emphasis><property moreinfo="none">Ok</property></emphasis>, and then <emphasis><property moreinfo="none">Ok</property></emphasis> again</para></listitem> +<listitem><para>Select <emphasis><property moreinfo="none">File > Save All</property></emphasis> from the menu bar</para></listitem> +</itemizedlist> +</section> + +<section id="Client-SideValidation"> +<?dbhtml filename="Client-SideValidation.html"?> +<title>Client-Side Validation</title> +<para>Client-side <property moreinfo="none">validation</property> uses a scripting language (like JavaScript) running in the client browser to actually do the <property moreinfo="none">validation</property>. In a Struts application using the <property moreinfo="none">Validation</property> Framework, however, you don't actually have to do any of the script coding. The <property moreinfo="none">Validation</property> Framework handles this.</para> +<para>To see how this works in our application, you'll just need to make a couple of modifications to one of the JSP files.</para> +<itemizedlist> +<listitem><para>Double-click inputname.jsp under <emphasis><property moreinfo="none">StrutsHello > WEB-ROOT(WebContent) > pages</property></emphasis> to open it for editing</para></listitem> +<listitem><para>Find the tag near the top and hit Return to make a new line under it</para></listitem> + <listitem><para>In the JBoss Tools Palette view to the right, open the Struts HTML folder and click on the javascript tag</para></listitem> +<listitem><para>Back in the editor, just in front of the closing slash for this inserted tag, hit Ctrl+Space and select "formName" from the prompting menu</para></listitem> +<listitem><para>Over in the Web Projects view, select GetNameForm under the <emphasis><property moreinfo="none">StrutsHello > Configuration > default > struts-config.xml > form-beans</property></emphasis> node, drag it, and drop it between the quotes in the editor</para></listitem> +<listitem><para>Modify the <emphasis role="bold"><property moreinfo="none"><html:form></property></emphasis> tag by inserting this attribute:</para></listitem> +</itemizedlist> +<programlisting format="linespecific" role="XML"><![CDATA[onsubmit="return validateGetNameForm(this)" +]]></programlisting> +<para></para> +<para>The file should now look like this:</para> +<programlisting format="linespecific" role="XML"><![CDATA[ +<%@ taglib uri="/WEB-INF/struts-html.tld" prefix="html" %> +<html:html> +<head> + <title>Input name</title> + <html:javascript formName="GetNameForm"/> +</head> +<body> + <html:form action="/greeting.do" onsubmit="return + <para>validateGetNameForm(this)"></para> + <table border="0" cellspacing="0" cellpadding="0"> + <tr> + <td><b>Input name:</b></td> + </tr> + <tr> + <td> + <html:text property="name" /> + <html:submit value=" Say Hello! " /> + </td> + </tr> + </table> + </html:form> +</body> +</html:html> +]]></programlisting> +<itemizedlist> +<listitem><para>Select<emphasis><property moreinfo="none"> File > Save </property></emphasis>from the menu bar</para></listitem> +<listitem><para>Start JBoss Application Server by clicking on its icon (a right-pointing arrow) in the toolbar</para></listitem> +<listitem><para>Click the Run icon or right click your project folder and select <emphasis><property moreinfo="none">Run As > Run on Server</property></emphasis></para></listitem> +</itemizedlist> +<figure float="0"> + <title>Run Icon</title> +<mediaobject> + <imageobject> + <imagedata fileref="images/struts_validation/struts_validation_1.png"></imagedata> + </imageobject> +</mediaobject> +</figure> +<itemizedlist><listitem><para>In the browser window, click on the "Say Hello!" button without having entered any name in the form</para></listitem></itemizedlist> +<para>A JavaScript error message should be displayed in an alert box.</para> +</section> +<section id="Server-SideValidation"> +<?dbhtml filename="Server-SideValidation.html"?> +<title>Server Side Validation</title> +<para>Server side validation does the validation inside the application on the server. In a Struts application using the Validation Framework, you still don't have to do any of the actual validation coding. The Validation Framework handles this. You will though have to make a few changes to the JSP file you modified for client-side validation along with a change to an action and a few changes to the form bean class.</para> +</section> + +<section id="EditingTheJSPFile"> +<?dbhtml filename="EditingTheJSPFile.html"?> +<title>Editing the JSP File</title> +<itemizedlist> +<listitem><para>Reopen inputname.jsp for editing</para></listitem> +<listitem><para>Delete the <emphasis role="italic"><property moreinfo="none">"onsubmit"</property></emphasis> attribute in the <emphasis role="bold"><property moreinfo="none"><html:form></property></emphasis> element that you put in for client-side validation</para></listitem> + +<listitem><para>Add an <emphasis role="bold"><property moreinfo="none"><html:errors></property></emphasis> tag after the <emphasis role="bold"><property moreinfo="none"><html:form></property></emphasis> tag</para></listitem> +</itemizedlist> +<para>The JSP file should now look like this:</para> + +<programlisting format="linespecific" role="XML"><![CDATA[<%@ taglib uri="/WEB-INF/struts-html.tld" prefix="html" %> +<html:html> +<head> + <title>Input name</title> + <html:javascript formName="GetNameForm"/> +</head> +<body> + <html:form action="/greeting.do"> + <table border="0" cellspacing="0" cellpadding="0"> + <tr> + <td><b>Input name:</b></td> + </tr> + <tr> + <td> + <html:text property="name" /> + <html:submit value=" Say Hello! " /> + </td> + </tr> + </table> + </html:form> + <html:errors /> +</body> +</html:html> +]]></programlisting> + +</section> + +<section id="EditingTheAction"> +<?dbhtml filename="EditingTheAction.html"?> +<title>Editing the Action</title> +<itemizedlist> +<listitem><para>In the Web Projects view, expand the node under the <emphasis><property moreinfo="none">StrutsHello > Configuration > default > struts-config.xml > action-mappings</property></emphasis> node, right-click the <emphasis><property moreinfo="none">/greeting</property></emphasis> action, and then select <emphasis><property moreinfo="none">Properties...</property></emphasis>from the context menu</para></listitem> + + <listitem><para>In the Edit Properties window, insert the cursor into the value column for the input property and click on the <property moreinfo="none">...</property> button</para></listitem> + + <listitem><para>In the dialog box, make sure the Pages tab is selected, select <emphasis><property moreinfo="none">StrutsHello > WEB-ROOT(WebContent) > pages > inputname.jsp</property></emphasis>, click the <emphasis><property moreinfo="none">Ok</property></emphasis> button, and then click on the <emphasis><property moreinfo="none">Close</property></emphasis> button</para></listitem> +</itemizedlist> +</section> +<section id="EditingTheFormBean"> +<?dbhtml filename="EditingTheFormBean.html"?> + +<title>Editing the Form Bean</title> +<itemizedlist> +<listitem><para>Right-click the <emphasis><property moreinfo="none">/greeting</property></emphasis> action again and select Open Form-bean Source to open the GetNameForm.java file for editing</para></listitem> +<listitem><para>Change the class that it extends from: <emphasis><property moreinfo="none">org.apache.struts.action.ActionForm</property></emphasis> to <emphasis><property moreinfo="none">org.apache.struts.validator.ValidatorForm</property></emphasis></para></listitem> +<listitem><para>Comment out a validate method</para></listitem> +</itemizedlist> +<para>The file should now look like this:</para> +<programlisting format="linespecific" role="JAVA"><![CDATA[package sample; +import javax.servlet.http.HttpServletRequest; +import org.apache.struts.action.ActionErrors; +import org.apache.struts.action.ActionMapping; +public class GetNameForm extends + +org.apache.struts.validator.ValidatorForm +{ + + private String name = ""; + + /** + * @return Returns the name. + */ + public String getName() + { + return name; + } + + /** + * @param name The name to set. + */ + public void setName(String name) + { + this.name = name; + } + + public GetNameForm () + { + } + + public void reset(ActionMapping actionMapping, + HttpServletRequest request) + { + this.name = ""; + } + + // public ActionErrors validate(ActionMapping actionMapping, + HttpServletRequest request) + { + // ActionErrors errors = new ActionErrors(); + // return errors; + // } + } +]]></programlisting> + +<itemizedlist> +<listitem><para>Select <emphasis><property moreinfo="none">File > Save All </property></emphasis>from the menu bar</para></listitem> +<listitem><para>Reload the application into JBoss AS by clicking on the "Change Time Stamp" icon (a finger pointing with a little star) in the toolbar</para></listitem> +<listitem><para>Run the application</para></listitem> +<listitem><para>In the browser window, click on the "Say Hello!" button without having entered any name in the form</para></listitem> +</itemizedlist> +<para>The error message should appear in a refreshed version of the form.</para> +</section> + +</chapter> + +<chapter id="relevant_resources" xml:base="file:///home/ochikvina/WORK/for_compare/trunk/struts/docs/struts_tools_tutorial/en/modules/relevant_resources.xml" xreflabel="relevant_resources"> + <?dbhtml filename="relevant_resources.html"?> + <chapterinfo> + <keywordset> + <keyword>JBoss Tools</keyword> + <keyword>Struts</keyword> + <keyword>Struts Application</keyword> + </keywordset> + </chapterinfo> + + <title>Other Relevant Resources on the topic</title> + + <para>Our reference: <ulink url="../../struts_tools_ref_guide/html_single/index.html">Struts Tools Reference Guide</ulink></para> + <para>Apache Struts: <ulink url="http://struts.apache.org/">Struts Technology</ulink></para> + <para>Struts 2: <ulink url="http://struts.apache.org/2.x/">Apache Struts 2</ulink></para> + <para>Get Started: <ulink url="http://struts.apache.org/2.x/docs/home.html">Struts Getting + Started</ulink></para> + <para>Struts on IBM: <ulink url="http://www.ibm.com/developerworks/library/j-struts/"><diffmk:wrapper diffmk:change="changed">Struts - + An open-source MVC implementation</diffmk:wrapper></ulink></para> + <para>FAQ: <ulink url="http://struts.apache.org/2.x/docs/faqs.html">Struts FAQ</ulink></para> + <para>Download: <ulink url="http://struts.apache.org/download.cgi#struts206"><diffmk:wrapper diffmk:change="changed">Release of Apache + Struts</diffmk:wrapper></ulink></para> + + <para diffmk:change="added"><diffmk:wrapper diffmk:change="added">Thus, this tutorial should help you to execute the hole development circle for building a + sample Struts-based Web application using </diffmk:wrapper><property diffmk:change="added" moreinfo="none"><diffmk:wrapper diffmk:change="added">JBoss Tools</diffmk:wrapper></property><diffmk:wrapper diffmk:change="added"> bundle of Eclipse + plugins starting from organizing a new Struts project and ending with the running and + deploying it onto the </diffmk:wrapper><property diffmk:change="added" moreinfo="none"><diffmk:wrapper diffmk:change="added">JBoss Server</diffmk:wrapper></property><diffmk:wrapper diffmk:change="added">.</diffmk:wrapper></para> + + <para diffmk:change="added"><diffmk:wrapper diffmk:change="added">To find out all the features of </diffmk:wrapper><property diffmk:change="added" moreinfo="none"><diffmk:wrapper diffmk:change="added">JBoss Tools</diffmk:wrapper></property><diffmk:wrapper diffmk:change="added"> for working with Struts + refer to our </diffmk:wrapper><ulink diffmk:change="added" url="../../struts_tools_ref_guide/html_single/index.html"><diffmk:wrapper diffmk:change="added">Struts Tools Reference Guide</diffmk:wrapper></ulink><diffmk:wrapper diffmk:change="added">. If you + still have questions you are always welcome on </diffmk:wrapper><ulink diffmk:change="added" url="http://www.jboss.com/index.html?module=bb&op=viewforum&f=201"><diffmk:wrapper diffmk:change="added">JBoss + Tools Forum</diffmk:wrapper></ulink><diffmk:wrapper diffmk:change="added">.</diffmk:wrapper></para> +</chapter> + + + +</book> Modified: branches/jbosstools-3.0.0.CR1/struts/docs/struts_tools_tutorial/en/modules/relevant_resources.xml =================================================================== --- branches/jbosstools-3.0.0.CR1/struts/docs/struts_tools_tutorial/en/modules/relevant_resources.xml 2008-12-19 19:33:13 UTC (rev 12776) +++ branches/jbosstools-3.0.0.CR1/struts/docs/struts_tools_tutorial/en/modules/relevant_resources.xml 2008-12-19 19:41:47 UTC (rev 12777) @@ -1,5 +1,5 @@ <?xml version='1.0' encoding='UTF-8'?> -<chapter id="relevant_resources" xreflabel="relevant_resources"> +<chapter id="relevant_resources" xreflabel="relevant_resources" role="updated"> <?dbhtml filename="relevant_resources.html"?> <chapterinfo> <keywordset>

15 years, 4 months

1
0
0 / 0

JBoss Tools SVN: r12776 - branches/jbosstools-3.0.0.CR1/struts/docs/struts_tools_ref_guide/en.

by jbosstools-commits＠lists.jboss.org

Author: smukhina Date: 2008-12-19 14:33:13 -0500 (Fri, 19 Dec 2008) New Revision: 12776 Added: branches/jbosstools-3.0.0.CR1/struts/docs/struts_tools_ref_guide/en/master_output.xml Modified: branches/jbosstools-3.0.0.CR1/struts/docs/struts_tools_ref_guide/en/master.xml Log: https://jira.jboss.org/jira/browse/JBDS-324 latest docs that are done for release 3.0.0.CR1 from trunk are added to branch master_output - the file to build guide versions with highlighted diff markers Modified: branches/jbosstools-3.0.0.CR1/struts/docs/struts_tools_ref_guide/en/master.xml =================================================================== --- branches/jbosstools-3.0.0.CR1/struts/docs/struts_tools_ref_guide/en/master.xml 2008-12-19 19:29:02 UTC (rev 12775) +++ branches/jbosstools-3.0.0.CR1/struts/docs/struts_tools_ref_guide/en/master.xml 2008-12-19 19:33:13 UTC (rev 12776) @@ -42,7 +42,7 @@ <holder>JBoss, a division of Red Hat Inc.</holder> </copyright> <releaseinfo> - Version: 3.0.0.beta1 + Version: 3.0.0.CR1 </releaseinfo> <abstract> Added: branches/jbosstools-3.0.0.CR1/struts/docs/struts_tools_ref_guide/en/master_output.xml =================================================================== --- branches/jbosstools-3.0.0.CR1/struts/docs/struts_tools_ref_guide/en/master_output.xml (rev 0) +++ branches/jbosstools-3.0.0.CR1/struts/docs/struts_tools_ref_guide/en/master_output.xml 2008-12-19 19:33:13 UTC (rev 12776) @@ -0,0 +1,1262 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" +"http://www.docbook.org/xml/4.3/docbookx.dtd" + +[ +<!ENTITY introduction SYSTEM "modules/introduction.xml"> +<!ENTITY projects SYSTEM "modules/projects.xml"> +<!ENTITY editors SYSTEM "modules/editors.xml"> +<!ENTITY modules SYSTEM "modules/modules.xml"> +<!ENTITY code_generation SYSTEM "modules/code_generation.xml"> +<!ENTITY config_file_debugger SYSTEM "modules/config_file_debugger.xml"> +<!ENTITY page_links_recognizer SYSTEM "modules/page_links_recognizer.xml"> +<!ENTITY project_verification SYSTEM "modules/project_verification.xml"> +<!ENTITY rel_resources_links SYSTEM "modules/rel_resources_links.xml"> + +<!ENTITY seamlink "../../seam/html_single/index.html"> +<!ENTITY aslink "../../as/html_single/index.html"> +<!ENTITY esblink "../../esb_ref_guide/html_single/index.html"> +<!ENTITY gsglink "../../GettingStartedGuide/html_single/index.html"> +<!ENTITY hibernatelink "../../hibernatetools/html_single/index.html"> +<!ENTITY jbpmlink "../../jbpm/html_single/index.html"> +<!ENTITY jsflink "../../jsf/html_single/index.html"> +<!ENTITY jsfreflink "../../jsf_tools_ref_guide/html_single/index.html"> +<!ENTITY jsftutoriallink "../../jsf_tools_tutorial/html_single/index.html"> +<!ENTITY strutsreflink "../../struts_tools_ref_guide/html_single/index.html"> +<!ENTITY strutstutoriallink "../../struts_tools_tutorial/html_single/index.html"> +<!ENTITY migrationlink "../../Exadel-migration/html_single/index.html"> + +]><book xmlns:diffmk="http://diffmk.sf.net/ns/diff"> + <bookinfo> + <title>Struts Tools Reference Guide</title> + + <author><firstname>Anatoly</firstname><surname>Fedosik</surname></author> + <author><firstname>Olga</firstname><surname>Chikvina</surname></author> + <author><firstname>Svetlana</firstname><surname>Mukhina</surname><email>smukhina(a)exadel.com</email></author> + + <pubdate>April 2008</pubdate> + <copyright> + <year>2007</year> + <year>2008</year> + <holder>JBoss, a division of Red Hat Inc.</holder> + </copyright> + <releaseinfo><diffmk:wrapper diffmk:change="changed"> + Version: 3.0.0.CR1 + </diffmk:wrapper></releaseinfo> + +<abstract> + <title></title> + <para> + <ulink url="http://download.jboss.org/jbosstools/nightly-docs/en/struts_tools_ref_gui...">PDF version</ulink> + </para> +</abstract> + + + </bookinfo> + + <toc></toc> + + +<chapter id="intoduction" xml:base="file:///home/ochikvina/WORK/for_compare/trunk/struts/docs/struts_tools_ref_guide/en/modules/introduction.xml"> + <?dbhtml filename="introduction.html"?> + + <chapterinfo> + <keywordset> + <keyword>JBoss Developer Studio</keyword> + <keyword>Eclipse</keyword> + <keyword>Java</keyword> + <keyword>JBoss</keyword> + </keywordset> + </chapterinfo> + + <title>Introduction</title> + + <para>If you prefer to develop web applications using Struts technology JBoss Tools also meet + your needs. The professional developer toolset provides all necessary editors and wizards + for creating Struts resources that enhances the process of building high-quality web + applications.</para> + <note> + <title>Note:</title> + <para>Note that JBoss Tools support the Struts 1.1, 1.2.x versions.</para> + </note> + + <para>In this guide you will learn how to take advantage of Struts support that <property moreinfo="none">JBoss Tools</property> + provide.</para> + + <section id="struts_key_features"> + <title>Key Features of Struts Tools</title> + + <para>For a start, we propose you to look through the table of main features of Struts + Tools:</para> + + <table> + + <title>Key Functionality for Struts Tools</title> + <tgroup cols="3"> + + <colspec align="left" colnum="1" colwidth="2*"></colspec> + <colspec colnum="2" colwidth="4*"></colspec> + <colspec align="left" colnum="3" colwidth="2*"></colspec> + + <thead> + <row> + <entry>Feature</entry> + <entry>Benefit</entry> + <entry>Chapter</entry> + </row> + </thead> + <tbody> + <row> + <entry><para>Struts Support</para></entry> + <entry><para>Step-by-step wizards for creating a new struts project with a number + of predefined templates, importing existing ones and adding struts + capabilities to non-struts web projects.</para></entry> + <entry> + <link linkend="projects">struts support</link> + </entry> + </row> + + <row> + <entry><para>Support for Struts Configuration File</para></entry> + <entry><para>Working on file using three modes: diagram, tree and source. + Synchronization between the modes and full control over the code. Easy + moving around the diagram using the Diagram Navigator. Working with + struts projects that have multiple modules. Possibility to use Struts + configuration file debugger allowing to set break points on struts + diagram and then launch the server in debug mode.</para></entry> + <entry> + <link linkend="struts_config_editor">graphical editor for struts</link> + <link linkend="config_file_debugger">configuration file debugger</link> + </entry> + </row> + + <row> + <entry><para>Support for Struts modules</para></entry> + <entry><para>A Struts module (struts-config.xml) is automatically created while + creating a new project. There is also possibility to add new ones or edit + already existing modules in your existing project or while importing Struts project.</para></entry> + <entry> + <link linkend="modules">modules</link> + </entry> + </row> + + <row> + <entry><para>Verification and Validation</para></entry> + <entry><para>All occuring errors will be immediately reported by verification + feature, no matter in what view you are working. Constant validation and + errors checking allows to catch many of the errors during development + process that significantly reduces development time.</para></entry> + <entry> + <link linkend="project_verification">verification and validation</link> + </entry> + + </row> + </tbody> + </tgroup> + </table> + + </section> + + <section> + <title>Other relevant resources on the topic</title> + + <para>All JBoss Developer Studio/JBoss Tools documentation you can find <ulink url="http://docs.jboss.org/tools/">here</ulink>.</para> + <para>The latest documentation builds are available <ulink url="http://download.jboss.org/jbosstools/nightly-docs/">here</ulink>.</para> + + </section> + +</chapter> + + +<chapter id="projects" xml:base="file:///home/ochikvina/WORK/for_compare/trunk/struts/docs/struts_tools_ref_guide/en/modules/projects.xml"> + <?dbhtml filename="projects.html"?> + + <chapterinfo> + <keywordset> + <keyword>JBoss Developer Studio</keyword> + <keyword>Eclipse</keyword> + <keyword>Java</keyword> + <keyword>JBoss</keyword> + </keywordset> + </chapterinfo> + + <title>Projects</title> + + <para>JBoss Tools provide the following functionality when working with Struts:</para> + + <itemizedlist> + <listitem> + <para>Create new <property moreinfo="none">Struts projects</property></para> + </listitem> + <listitem> + <para>Import (open) existing Struts projects. You can import any project + structure</para> + </listitem> + <listitem> + <para>Add <property moreinfo="none">Struts capabilities</property> to any existing Eclipse + project</para> + </listitem> + <listitem> + <para>Import and add Struts capabilities to any existing project created outside + Eclipse.</para> + </listitem> + </itemizedlist> + <para>Now, we'll focus on all these points more fully.</para> + + <section id="CreatingANewStrutsProjec745t"> + + <title>Creating a New Struts Project</title> + + + <para>JBoss Tools provides a New Struts Project Wizard that radically simplifies the process + for getting started with a new Struts project. You just need to follow these steps:</para> + <itemizedlist> + <listitem> + <para>Select<emphasis> + <property moreinfo="none">File > New > Project...</property> + </emphasis> from the menu bar. Then, select <emphasis> + <property moreinfo="none">JBoss Tools Web > Struts > Struts Project</property> + </emphasis> in this dialog box. Click <emphasis> + <property moreinfo="none">Next</property>: </emphasis></para> + </listitem> + </itemizedlist> + <figure float="0"> + <title>Selecting Struts Wizard</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_2.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + <itemizedlist> + <listitem> + <para>On this form, provide the <property moreinfo="none">Project Name</property>. You can also + select where to create the project or use the default path.</para> + <para>Next to <property moreinfo="none">Struts Environment</property> set which Struts version to + use.</para> + </listitem> + </itemizedlist> + + <figure float="0"> + <title>Creating Struts Project</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_3.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <tip> + <title>Tip:</title> + <para>Don't put spaces in project names since some OS could experience problems + with their processing and searching these files.</para> + </tip> + + <para>You can select the KickStart template, then the project created will include a simple + Hello World type application that is ready to run.</para> + + <figure float="0"> + <title>Choosing Struts Template </title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_3_1.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <itemizedlist> + <listitem> + <para>Next, you register this application with the current servlet container defined + for your workspace (JBoss AS, by default) in order to allow you to test your + application more easily while still developing it. A new entry will be added in + the servlet container configuration file to enable running the application + in-place (called null deployment or link deployment). Uncheck the <emphasis role="italic"> + <property moreinfo="none">"Target Server"</property> + </emphasis> check box if for some reason you don't want to register + your application at this point.</para> + </listitem> + </itemizedlist> + <figure float="0"> + <title>Registering The Project at Server</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_4.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + <itemizedlist> + <listitem> + <para>On the next form, you can select the TLD files to include in this + project:</para> + </listitem> + </itemizedlist> + <figure float="0"> + <title>Selecting Tag Libraries</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_5.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>After the project is created, you should have the following project structure (if you + used the KickStart template):</para> + + <figure float="0"> + <title>Project Structure</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_6.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <tip> + <title>Tip:</title> + <para>If you want to hide the jar files from Web App Libraries in view, select the + down-pointing arrow in the upper right corner, select + <emphasis>Filters...</emphasis>, check the box next to Name filter patterns + (matching names will be hidden), and type *.jar into the field. Then, click OK. + </para> + </tip> + </section> + <section id="ImportingAnExistingStrutsProjectWithAnyStructure9653"> + + <title>Importing an Existing Struts Project with Any Structure</title> + + <para>For detailed information on migration projects to JBoss Developer Studio see <ulink url="../../Exadel-migration/html_single/index.html">Migration Guide</ulink>.</para> + + </section> + <section id="AddingStrutsCapabilityToAnExistingWebApplication532"> + + <title>Adding Struts Capability to an Existing Web Application</title> + + <para>Here, we'll consider how to add Struts functionality (Struts libraries, tag + libraries and a Struts configuration file) to any existing Web application project in + your Eclipse workspace.</para> + + <para>By adding a Struts Nature to your project, you can now edit files using JBoss Tools + editors, such as the <link linkend="struts_config_editor">Struts configuration + editor</link> and the JBoss Tools JSP editor. To take advantage of this just right-click + the project and select <emphasis> + <property moreinfo="none">JBoss Tools > Add Struts Capabilities</property> + </emphasis> from the context menu. This will start the process of adding all necessary + libraries and files to make a Web Struts project from your one.</para> + + <figure float="0"> + <title>Adding Struts Capabilities</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_7.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>In the wizard you should point to location of your deployment descriptor file web.xml + and name of the project.</para> + + <figure float="0"> + <title>Choosing Project Location</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_8.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + <para>After hitting <emphasis> + <property moreinfo="none">Next</property>, </emphasis> you will see the following screen. This + screen simply means that you need to add at least one Struts module to your project to + make this project a Struts project. Adding a Struts module means that a new + struts-config.xml will be added to your project and registered in the web.xml file. In + addition, all required Struts libraries will be added. To add a Struts module, select + the <emphasis> + <property moreinfo="none">Add Struts Support</property> + </emphasis> button.</para> + <figure float="0"> + <title>Project Modules</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_9.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>Here you can select what Struts <property moreinfo="none">Version</property>, <property moreinfo="none">Servlet + Class</property>, <property moreinfo="none">URL Pattern</property> and <property moreinfo="none">TLD</property>s to add + to this project.</para> + + <figure float="0"> + <title>Selecting Struts Support Options</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_10.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>When done, you will see the default Struts module configuration information. See how + to Edit <link linkend="modules">Struts modules</link>.</para> + + <figure float="0"> + <title>Project Configuration Information</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_11.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>On the last screen you can set the different folders for your project as well as + register this application with a servlet container. If you want the libraries (.jar + files) will be automatically added to your project, click on the checkbox <emphasis> + <property moreinfo="none">Add Libraries</property>.</emphasis></para> + + <figure float="0"> + <title>Registering the Project at Server</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_12.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>When done, you can open end edit the struts-config.xml file using usefull Struts + configuration file editor provided by JBDS. (The Struts configuration is shown below in + the Tree viewer).</para> + + <figure float="0"> + <title>Struts-config.xml File</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_13.png" scale="75"></imagedata> + </imageobject> + </mediaobject> + </figure> + </section> + +</chapter> + + +<chapter id="editors" xml:base="file:///home/ochikvina/WORK/for_compare/trunk/struts/docs/struts_tools_ref_guide/en/modules/editors.xml"> + <?dbhtml filename="editors.html"?> + <chapterinfo> + <keywordset> + <keyword>JBoss Developer Studio</keyword> + <keyword>Eclipse</keyword> + <keyword>Struts Tools</keyword> + <keyword>Java</keyword> + <keyword>JBoss</keyword> + </keywordset> + </chapterinfo> + + <title>Editors</title> + <para>In this chapter we'll introduce you to featured graphical editors for specific + Struts files such as Struts Configuration files, Tiles files and Struts Validation files.</para> + <section id="struts_config_editor"> + + <title>Graphical Editor for Struts Configuration Files</title> + <para>First, let's dwell on the Struts Configuration file editor.</para> + <para>This editor has three views with different representation of <emphasis> + <property moreinfo="none">struts-config.xml</property>: </emphasis>Diagram, Tree and Source. The + views can be selected via the tabs at the bottom of the editor. Any changes made in one + view are immediately visible when you switch to any other view.</para> + + <para>Now, we'll consider every view in more detail.</para> + <section id="StrutsDiagramMode453"> + + <title>Diagram View</title> + + <para>The Diagram view graphically displays the Web flow of the application defined in + the Struts configuration file.</para> + + <figure float="0"> + <title>Diagram View</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_14.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>The Diagram view allows to edit navigation in your Struts application. Just by + right-clicking anywhere on the diagram, you can use a context menu to create the + building blocks of a Struts application:</para> + <itemizedlist> + <listitem> + <para>Actions</para> + </listitem> + <listitem> + <para>Global forwards</para> + </listitem> + <listitem> + <para>Global exceptions</para> + </listitem> + <listitem> + <para>JSP Pages</para> + </listitem> + </itemizedlist> + + <figure float="0"> + <title>Diagram Context Menu</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_15.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>Along the upper-left side of the editor is a stack of seven icons for changing the + behavior of the cursor in the diagram. </para> + + <figure float="0"> + <title>Editor Icons</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_16.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>The first icon switches to the default regular selection cursor, the second to the + marquee selection cursor and the third to the new connection cursor. The last four + icons switch the cursor to an insert cursor for each type of Struts build block + listed above (and in the order listed).</para> + + <para>For instance, clicking on the first of these four icons (the one with the gears) + will switch the cursor to insert actions. Clicking anywhere in the diagram with this + cursor has the same effect as right-click and selecting <emphasis> + <property moreinfo="none">Add > Action...</property> + </emphasis> from the context menu with the regular cursor active. It's just + more efficient to use this cursor if you're adding more than one action at + once.</para> + + + </section> + <section id="StrutsTreeMode42"> + + <title>Tree View</title> + + <para>The Tree view represents the different elements of the Struts application that are + organized into functional categories on the left-hand side and a form for editing + the properties of currently selected items on the right-hand side.</para> + + <figure float="0"> + <title>Tree View</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_17.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>You can also right-click on any node in the category tree and perform appropriate + operations through a context menu. For instance, by right-clicking on the + action-mappings category node, you can add new actions to the application.</para> + + <figure float="0"> + <title>Tree Context Menu</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_18.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + </section> + <section id="StrutsSourceMode9655"> + + <title>Source View</title> + + <para>In the Source view, you have complete editing control of the underlying XML + coding.</para> + + <figure float="0"> + <title>Source View</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_19.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>When working in Source view, you always have all the following features available:</para> + <itemizedlist> + <listitem> + <para>Content Assist</para> + </listitem> + <listitem> + <para>Open On Selection</para> + </listitem> + <listitem> + <para>File Folding</para> + </listitem> + </itemizedlist> + <para>You can take advantage of <ulink url="../../jsf/html_single/index.html#CodeAssistAndDynamicCodeAssist42BasedOnProjectData">code assist</ulink>.</para> + <figure float="0"> + <title>Code Assist</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_20.png" scale="85"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>The editor will also immediately flag any errors.</para> + + <figure float="0"> + <title>Errors in Source View</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_21.png" scale="85"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>Finally, you can use the Outline view with the editor to easily navigate through + the file.</para> + + <figure float="0"> + <title>Outline View</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_22.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>Find more information about editor features <ulink url="../../jsf/html_single/index.html#editors_features">here</ulink>.</para> + </section> + </section> + + <section id="GraphicalEditorForTilesFiles132"> + + <title>Graphical Editor for Tiles Files</title> + <para>Here, you'll know how to make use of the special graphical editor for Tiles configuration files.</para> + <para>The editor has three main views: Tree, Diagram and Source. + The views can be selected via the tabs at the bottom of the editor. Any changes made in + one view are immediately visible when you switch to any other view.</para> + + <para>Before we consider each view of the editor, let's look at the way of creating new Tiles files.</para> + <section id="CreateNewTilesFile1422"> + + <title>Create New Tiles File</title> + + <para>To create new Tiles files, right click any folder and select <emphasis> + <property moreinfo="none">New > Tiles File</property>. </emphasis></para> + <figure float="0"> + <title>Creating a New Tiles File</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_23.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + </section> + <section id="StrutsTreeView896"> + + <title>Tree View</title> + + <para>The Tree view represents the different elements of the Tiles file that are + organized into functional categories on the left-hand side and a form for editing + the properties of currently selected items on the right-hand side.</para> + <figure float="0"> + <title>Tree View</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_24.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>To edit the file, simply right click any node and select among the available + actions.</para> + <figure float="0"> + <title>Editing in Tiles Editor</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_25.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + </section> + <section id="StrutsDiagramView4643"> + + <title>Diagram View</title> + + <para>The Diagram view allows you to create complex Tiles files in the form of a + diagram.</para> + <figure float="0"> + <title>Diagram Mode</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_26.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>To create new definitions, simply right click anywhere in the diagram.</para> + <figure float="0"> + <title>Creating New Definition</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_27.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>You can also use the Diagram toolbar to make editing easier.</para> + <figure float="0"> + <title>Diagram Toolbar</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_28.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para> It contains four icons for changing the cursor state. The first one is the + default cursor state for selecting existing nodes. The second icon is marquee + selector. The third is used for creating new connections and the last one is for + adding definition template to the content.</para> + </section> + <section id="StrutsSource75"> + + <title>Source</title> + + <para>The other view of the <property moreinfo="none">Tiles editor</property> is the Source view that + gives you full control over the source. Any changes here will immediately appear in + other modes when you switch to them.</para> + + <para>When working in Source view, you always have all following features available:</para> + <itemizedlist> + <listitem> + <para>Content Assist</para> + </listitem> + <listitem> + <para>Open On Selection</para> + </listitem> + </itemizedlist> + + <figure float="0"> + <title>Source View</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_29.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + <para><ulink url="../../jsf/html_single/index.html#CodeAssistAndDynamicCodeAssist42BasedOnProjectData">Code + assist</ulink> is available in the Source mode.</para> + <figure float="0"> + <title>Code Assist</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_30.png" scale="85"></imagedata> + </imageobject> + </mediaobject> + </figure> + <para>Any errors are immediately reported as shown below:</para> + <figure float="0"> + <title>Errors Reporting</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_31.png" scale="75"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>You can also use the Outline view together with the editor's Source mode. + It provides an easier navigation through the file.</para> + <figure float="0"> + <title>Outline View</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_32.png" scale="85"></imagedata> + </imageobject> + </mediaobject> + </figure> + </section> + </section> + + <section id="GraphicalEditorForStrutsValidationFiles86"> + + <title>Graphical Editor for Struts Validation Files</title> + + <para>Providing full support for development Struts applications JBoss Tools comes with a + visual validation editor. To open the editor double-click on the validation file or if you don't have it create a new one.</para> + + <para>To create a new validation file, right click any folder in + Project Explorer and select <emphasis> + <property moreinfo="none">File > New > Other...</property> + </emphasis>from the context menu and then <emphasis> + <property moreinfo="none">JBoss Tools Web > Struts > Validation File</property>. </emphasis></para> + <figure float="0"> + <title>Creating New Validation File</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_33.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>The validation editor works with five modes: Formsets, Validators, Constants and + standard Tree and Source that you can easily switch over using tabs at the bottom of the + editor.</para> + <para>The Formsets view shows forms and their elements on the left side and the dialogue for + defining their validation rules on the right side.</para> + <figure float="0"> + <title>Formsets View</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_34.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>The Constants view let you set constant values for your validation rules.</para> + <figure float="0"> + <title>Constansts View</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_35.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>The validation file can also be viewed in a Tree view.</para> + <figure float="0"> + <title>Tree View</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_36.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>At any point you have full control over the source by switching to the Source view. + Any editing in this view will immediately be available in other views of the editor.</para> + <figure float="0"> + <title>Source View</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_37.png" scale="85"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>You can also open your own custom or Struts-standard <emphasis> + <property moreinfo="none">validation-rules.xml</property> + </emphasis> file.</para> + <para>The Validators view shows the validation rules for a selected validator. You can of + course add your own rules.</para> + <figure float="0"> + <title>Validators View</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_38.png" scale="75"></imagedata> + </imageobject> + </mediaobject> + </figure> + <para>Here are the validation rules shown in the Source mode.</para> + <figure float="0"> + <title>Validation Rules</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_39.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + </section> +</chapter> + + +<chapter id="modules" xml:base="file:///home/ochikvina/WORK/for_compare/trunk/struts/docs/struts_tools_ref_guide/en/modules/modules.xml"> + <?dbhtml filename="modules.html"?> + <chapterinfo> + <keywordset> + <keyword>JBoss Developer Studio</keyword> + <keyword>Eclipse</keyword> + <keyword>Struts Tools</keyword> + <keyword>Java</keyword> + <keyword>JBoss</keyword> + </keywordset> + </chapterinfo> + + <title>Modules</title> + + <para>JBoss Tools support working with Struts projects that have + multiple modules. You can easily do the following:</para> + <itemizedlist> + <listitem> + <para>Add new modules</para> + </listitem> + <listitem> + <para>Edit modules for an existing project or during Struts project + import</para> + </listitem> + </itemizedlist> + <para>Now, let's discuss this functionality in more detail.</para> + <section id="WhenImportingAStrutsProject432"> + + <title>When Importing a Struts Project</title> + + <para>During Struts project import, if the project has multiple modules, you + will see a screen with all existing modules. You can select each + module and edit its details.</para> + + <figure float="0"> + <title>Configuring Project Modules</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_40.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + </section> + <section id="EditingModulesInAnExistingProject1"> + + <title>Editing Modules in an Existing Project</title> + <para>To edit modules in an existing project, right click the project and + select <emphasis> + <property moreinfo="none">JBoss Tools > Modules Configuration</property>. + </emphasis></para> + <figure float="0"> + <title>Choosing Modules Configuration</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_41.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + <para>You will see the same screen as above where you will be able to select + a module and edit its details.</para> + <figure float="0"> + <title>Modules Configuration</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_42.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + </section> + <section id="AddingNewModules1"> + + <title>Adding New Modules</title> + + <para>Adding a new module is very simple. First switch to Web Project view. + Expand your project to the Configuration folder. Under that folder + you should see the current modules. Right click on Configuration and + select <emphasis> + <property moreinfo="none">New > Struts Config</property>. </emphasis></para> + <figure float="0"> + <title>Adding New Modules</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_43.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + <para>You will see the screen below. You can specify a new module name and + also add the new Struts configuration file to web.xml file.</para> + <figure float="0"> + <title>Adding New Modules</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_44.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + </section> +</chapter> + + +<chapter id="code_generation" xml:base="file:///home/ochikvina/WORK/for_compare/trunk/struts/docs/struts_tools_ref_guide/en/modules/code_generation.xml"> + <?dbhtml filename="code_generation.html"?> + + <chapterinfo> + <keywordset> + <keyword>JBoss Developer Studio</keyword> + <keyword>Eclipse</keyword> + <keyword>Struts Tools</keyword> + <keyword>Java</keyword> + <keyword>JBoss</keyword> + </keywordset> + </chapterinfo> + + <title>Code Generation</title> + + <para>JBoss Tools comes with a <property moreinfo="none">code generation</property> + feature. You can generate stub code for Struts Actions, FormBeans, Forwards + and Exceptions.</para> + + <para>The code generation that JBoss tooling provides is based on Velocity templates + which can be modified for your use. The templates are located at <emphasis> + <property moreinfo="none"> {JBossStudioHome} > templates > + codegeneration</property>. </emphasis></para> + + <para>There are a number of ways to invoke code generation. One is simply + right-clicking the Struts diagram and selecting <emphasis> + <property moreinfo="none">Generate Java Code....</property> + </emphasis></para> + + <figure float="0"> + <title>Selecting Generate Java Code</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_45.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>On this screen you can select for which elements to generate code. If you + select Next you will be able to specify more options for each of the + categories you selected.</para> + + <figure float="0"> + <title>Generate - Step 1</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_46.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <tip> + <title>Tip:</title> + <para>Please be careful not to override your existing files.</para> + </tip> + + <para>When generation is complete, a result window will appear letting you know how + many classes were generated:</para> + + <figure float="0"> + <title>Generation Finished</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_47.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>You don't always have to generate code for all elements at once. You + can invoke generation for just an individual Struts artifact as well. + Right-click an element on the diagram of the Struts configuration file and + select <emphasis> + <property moreinfo="none">Generate Java Code...</property> + </emphasis> from the context menu.</para> + + <figure float="0"> + <title>Generation For Individual Struts Artifact</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_48.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>The same can be done from within the Tree viewer for the editor of the Struts + configuration file.</para> + + <figure float="0"> + <title>Generation in Struts Config Editor</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_49.png"></imagedata> + </imageobject> + </mediaobject> + </figure> +</chapter> + +<chapter id="config_file_debugger" xml:base="file:///home/ochikvina/WORK/for_compare/trunk/struts/docs/struts_tools_ref_guide/en/modules/config_file_debugger.xml"> + <?dbhtml filename="config_file_debugger.html"?> + <chapterinfo> + <keywordset> + <keyword>JBoss Developer Studio</keyword> + <keyword>Eclipse</keyword> + <keyword>Struts Tools</keyword> + <keyword>Java</keyword> + <keyword>JBoss</keyword> + </keywordset> + </chapterinfo> + + <title>Struts Configuration File Debugger</title> + + <para>JBoss Tools come with <property moreinfo="none">Struts configuration file + debugger</property>. It allows you to set break points on Struts diagram and + then simply launch the server in debug mode.</para> + + <para>Simply right click an Action or a page and select Add <emphasis> + <property moreinfo="none">Breakpoint</property>. </emphasis></para> + <figure float="0"> + <title>Adding Breakpoint</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_50.png"></imagedata> + </imageobject> + </mediaobject> + </figure> +</chapter> + +<chapter id="page_links_recognizer" xml:base="file:///home/ochikvina/WORK/for_compare/trunk/struts/docs/struts_tools_ref_guide/en/modules/page_links_recognizer.xml"> + <?dbhtml filename="page_links_recognizer.html"?> + + <chapterinfo> + <keywordset> + <keyword>JBoss Developer Studio</keyword> + <keyword>Eclipse</keyword> + <keyword>Java</keyword> + <keyword>JBoss</keyword> + </keywordset> + </chapterinfo> + + <title>Customizable Page Links Recognizer</title> + + <para><property moreinfo="none">Custom page links</property> allow you to define custom Struts page + links that will be recognizable in the Struts application diagram. You can + define these links by selecting <emphasis> + <property moreinfo="none">Window > Preferences</property> + </emphasis> from the menu bar and then selecting <emphasis> + <property moreinfo="none">JBoss Tools > Web > Struts > Customization</property> + </emphasis> from the Preferences dialog box.</para> + <figure float="0"> + <title>Customization Panel</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_51.png"></imagedata> + </imageobject> + </mediaobject> + </figure> +</chapter> + +<chapter id="project_verification" xml:base="file:///home/ochikvina/WORK/for_compare/trunk/struts/docs/struts_tools_ref_guide/en/modules/project_verification.xml"> + <?dbhtml filename="project_verification.html"?> + <chapterinfo> + <keywordset> + <keyword>JBoss Developer Studio</keyword> + <keyword>Eclipse</keyword> + <keyword>Struts Tools</keyword> + <keyword>Java</keyword> + <keyword>JBoss</keyword> + </keywordset> + </chapterinfo> + + <title>Struts Project Verification</title> + + <para>In this section we'll consider one more functionality that JBoss Tools provide for Struts + projects, namely adjusting projects verification.</para> + + <para>To configure Struts project verification select <emphasis> + <property moreinfo="none">Window > Preferences</property> + </emphasis> from the menu bar, select <emphasis> + <property moreinfo="none">JBoss Tools > Web > Verification</property> + </emphasis> from the Preferences dialog box and then expand the + Struts Rules node.</para> + <figure float="0"> + <title>Struts Rules</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/verif_valid/verif_valid_8.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + <para>Suppose you are working in the Source viewer for a Struts + configuration file as shown below:</para> + <figure float="0"> + <title>Struts Configuration File</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/verif_valid/verif_valid_9.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + <para>While typing a class name or entering it from the graphical editor, + you might make a minor typo (like <emphasis role="italic"> + <property moreinfo="none">"sample.GreetingAction1"</property> + </emphasis> instead of <emphasis role="italic"> + <property moreinfo="none">"sample.GreetingAction"</property> + </emphasis>). After saving the file, + <property moreinfo="none">verification</property> checks to make sure everything is + correct and finds the error below:</para> + <figure float="0"> + <title>Error Reporting</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/verif_valid/verif_valid_10.png" scale="75"></imagedata> + </imageobject> + </mediaobject> + </figure> + <para>Notice that the Package Explorer View shows a marked folder and a + marked file where the error is.</para> + <para>You can place the cursor over the line with the error to view a + detailed error message:</para> + <figure float="0"> + <title>Error Message</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/verif_valid/verif_valid_11.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + <para>The verification also checks to make sure you have specified the + correct JSP page for the forward:</para> + <figure float="0"> + <title>JSP Page Verification</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/verif_valid/verif_valid_12.png" scale="75"></imagedata> + </imageobject> + </mediaobject> + </figure> + <para>Once you place the cursor over the line, you can see the error + message:</para> + <figure float="0"> + <title>Error Message</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/verif_valid/verif_valid_13.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + <para>You can always invoke the verification by switching to the Diagram + viewer, right-clicking and selecting <emphasis> + <property moreinfo="none">Verify</property> + </emphasis> from the context menu:</para> + <figure float="0"> + <title>Verify Command</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/verif_valid/verif_valid_14.png"></imagedata> + </imageobject> + </mediaobject> + </figure> +</chapter> + +<chapter id="rel_resources_links" xml:base="file:///home/ochikvina/WORK/for_compare/trunk/struts/docs/struts_tools_ref_guide/en/modules/rel_resources_links.xml"> + <?dbhtml filename="rel_resources_links.html"?> + <chapterinfo> + <keywordset> + <keyword>JBoss Developer Studio</keyword> + <keyword>Eclipse</keyword> + <keyword>Struts Tools</keyword> + <keyword>Java</keyword> + <keyword>JBoss</keyword> + </keywordset> + </chapterinfo> + + <title>Relevant Resources Links</title> + + <para>Find out necessary information on <ulink url="http://struts.apache.org/">Struts + technology</ulink> if you don't know enough.</para> + + <para>In summary, this reference should help you to get familiar with those parts of + <property moreinfo="none">JBoss Tools</property> which are meant for development with Struts + technology. If you've carefully gone through the document, you should know + now how to create/import Struts project or enable Struts capabilities for an + existing web project as well as organize and edit all necessary staff for your + Struts application using a set of views and editors provided by <property moreinfo="none">JBoss + Tools</property>.</para> + + <para>If you'd like to contribute your feedback is always appreciated. You can + leave your questions and suggestions on our <ulink url="http://www.jboss.com/index.html?module=bb&op=viewforum&f=201">Forum</ulink>.</para> +</chapter> + +</book>

15 years, 4 months

1
0
0 / 0

JBoss Tools SVN: r12775 - in branches/jbosstools-3.0.0.CR1/jsf/docs/jsf_tools_tutorial/en: modules and 1 other directory.

by jbosstools-commits＠lists.jboss.org

Author: smukhina Date: 2008-12-19 14:29:02 -0500 (Fri, 19 Dec 2008) New Revision: 12775 Added: branches/jbosstools-3.0.0.CR1/jsf/docs/jsf_tools_tutorial/en/master_output.xml Modified: branches/jbosstools-3.0.0.CR1/jsf/docs/jsf_tools_tutorial/en/modules/relevant_resources.xml Log: https://jira.jboss.org/jira/browse/JBDS-324 docs from trunk are added to branch master_output - the file to build guide versions with highlighted diff markers Added: branches/jbosstools-3.0.0.CR1/jsf/docs/jsf_tools_tutorial/en/master_output.xml =================================================================== --- branches/jbosstools-3.0.0.CR1/jsf/docs/jsf_tools_tutorial/en/master_output.xml (rev 0) +++ branches/jbosstools-3.0.0.CR1/jsf/docs/jsf_tools_tutorial/en/master_output.xml 2008-12-19 19:29:02 UTC (rev 12775) @@ -0,0 +1,798 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" +"http://www.docbook.org/xml/4.3/docbookx.dtd" + +[<!ENTITY introduction SYSTEM "modules/introduction.xml"> +<!ENTITY jsf_application SYSTEM "modules/jsf_application.xml"> +<!ENTITY adding_navigation SYSTEM "modules/adding_navigation.xml"> +<!ENTITY adding_managed_bean SYSTEM "modules/adding_managed_bean.xml"> +<!ENTITY jsp_view_files SYSTEM "modules/jsp_view_files.xml"> +<!ENTITY start_page SYSTEM "modules/start_page.xml"> +<!ENTITY running_application SYSTEM "modules/running_application.xml"> +<!ENTITY relevant_resources SYSTEM "modules/relevant_resources.xml"> + +<!ENTITY seamlink "../../seam/html_single/index.html"> +<!ENTITY aslink "../../as/html_single/index.html"> +<!ENTITY esblink "../../esb_ref_guide/html_single/index.html"> +<!ENTITY gsglink "../../GettingStartedGuide/html_single/index.html"> +<!ENTITY hibernatelink "../../hibernatetools/html_single/index.html"> +<!ENTITY jbpmlink "../../jbpm/html_single/index.html"> +<!ENTITY jsflink "../../jsf/html_single/index.html"> +<!ENTITY jsfreflink "../../jsf_tools_ref_guide/html_single/index.html"> +<!ENTITY jsftutoriallink "../../jsf_tools_tutorial/html_single/index.html"> +<!ENTITY strutsreflink "../../struts_tools_ref_guide/html_single/index.html"> +<!ENTITY strutstutoriallink "../../struts_tools_tutorial/html_single/index.html"> + +]><book xmlns:diffmk="http://diffmk.sf.net/ns/diff"> + + <bookinfo> + <title>JSF Tools Tutorial</title> + + <author><firstname>Anatoly</firstname><surname>Fedosik</surname></author> + <author><firstname>Olga</firstname><surname>Chikvina</surname></author> + <author><firstname>Svetlana</firstname><surname>Mukhina</surname><email>smukhina(a)exadel.com</email></author> + + <pubdate>April 2008</pubdate> + <copyright> + <year>2007</year> + <year>2008</year> + <holder>JBoss, a division of Red Hat Inc.</holder> + </copyright> + + <releaseinfo><diffmk:wrapper diffmk:change="changed"> + Version: 3.0.0.CR1 + </diffmk:wrapper></releaseinfo> + + +<abstract> + <title></title> + <para> + <ulink url="http://download.jboss.org/jbosstools/nightly-docs/en/struts_tools_tutoria...">PDF version</ulink> + </para> +</abstract> + + + </bookinfo> + + <toc></toc> + + + +<chapter id="introduction" xml:base="file:///home/ochikvina/WORK/for_compare/trunk/jsf/docs/jsf_tools_tutorial/en/modules/introduction.xml" xreflabel="introduction"> + <?dbhtml filename="introduction.html"?> + <chapterinfo> + <keywordset> + <keyword>JBoss Developer Studio</keyword> + <keyword>Eclipse</keyword> + <keyword>Java</keyword> + <keyword>JBoss</keyword> + </keywordset> + </chapterinfo> + <title>Introduction</title> + <para>The following chapters describe how to deal with classic/old style of JSF development. We + recommend users to use <ulink url="../../seam/html_single/index.html">JBoss + Seam</ulink> to simplify development, but until then you can read about classical JSF + usage here.</para> + + <para>Thus, in this document we are going to show you how to create a simple <property moreinfo="none">JSF application + </property>using <property moreinfo="none">JBoss Tools</property> plugins for Eclipse. The completed + application will ask a user to enter a name and click a button. The resulting new page + will display the familiar message, "Hello <name>!" This + tutorial will show you how to create and run such an application from the beginning along the + way demonstrating some of the powerful features of <property moreinfo="none">JBoss Tools</property>.</para> + + <section> + <title>Other relevant resources on the topic</title> + <para>All JBoss Developer Studio/JBoss Tools documentation you can find <ulink url="http://www.jboss.com/products/devstudio/docs">here</ulink>.</para> + <para>The latest documentation builds are available <ulink url="http://download.jboss.org/jbosstools/nightly-docs/">here</ulink>.</para> + </section> + +</chapter> + + +<chapter id="jsf_application" xml:base="file:///home/ochikvina/WORK/for_compare/trunk/jsf/docs/jsf_tools_tutorial/en/modules/jsf_application.xml" xreflabel="jsf_application"> + <?dbhtml filename="jsf_application.html"?> + <chapterinfo> + <keywordset> + <keyword>JBoss Developer Studio</keyword> + <keyword>JSF application</keyword> + <keyword>Java</keyword> + </keywordset> + </chapterinfo> + + <title>Creating a Simple JSF Application</title> + + <para>Firstly, we assume that you have already launched Eclipse with <property moreinfo="none">JBoss Tools</property> + plug-ins installed and also that the <property moreinfo="none">Web Development perspective</property> is the current + one. (If not, make it active by selecting <emphasis> + <property moreinfo="none">Window > Open Perspective > Web Development</property> + </emphasis> from the menu bar or by selecting <emphasis> + <property moreinfo="none">Window > Open Perspective > Other...</property> + </emphasis> from the menu bar and then selecting <emphasis> + <property moreinfo="none">Web Development</property> + </emphasis> from the Select Perspective dialog box.)</para> + + <section id="setting_up_the_project"> + <?dbhtml filename="SettingUpTheProject.html"?> + <title>Setting Up the Project</title> + <para>Now we are going to create a new project for the application.</para> + <itemizedlist> + <listitem> + <para>For that go to the menu bar and select <emphasis> + <property moreinfo="none">File > New > Project...</property> + </emphasis></para> + </listitem> + <listitem> + <para>Select <emphasis> + <property moreinfo="none">JBoss Tools Web > JSF > JSF Project</property> + </emphasis> in the New Project dialog box</para> + </listitem> + <listitem> + <para>Click <emphasis> + <property moreinfo="none">Next</property> + </emphasis></para> + </listitem> + <listitem> + <para>Enter "jsfHello" as the project name.</para> + </listitem> + <listitem> + <para>Leave everything else as is, and click <emphasis> + <property moreinfo="none">Finish</property> + </emphasis></para> + </listitem> + + </itemizedlist> + </section> + + <section id="TheJSFApplicationConfigurationFile"> + <?dbhtml filename="TheJSFApplicationConfigurationFile.html"?> + <title>JSF Configuration File</title> + <para>A jsfHello node should appear in the upper-left Package Explorer view.</para> + <figure float="0"> + <title>Package Explorer View</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/jsf_application/jsf_application_1.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + <itemizedlist> + <listitem> + <para>Click the plus sign next to <emphasis> + <property moreinfo="none">jsfHello</property> + </emphasis> to reveal the child nodes</para> + </listitem> + <listitem> + <para>Click the plus sign next to <emphasis> + <property moreinfo="none">WebContent</property> + </emphasis> under jsfHello</para> + </listitem> + <listitem> + <para>Click the plus sign next to <emphasis> + <property moreinfo="none">WEB-INF</property> + </emphasis> under WebContent</para> + </listitem> + + <listitem> + <para>Then double-click on the <property moreinfo="none">faces-config.xml</property> node to display + the JSF application configuration file editor</para> + </listitem> + </itemizedlist> + <figure float="0"> + <title>Configuration File Editor</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/jsf_application/jsf_application_2.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + </section> +</chapter> + + +<chapter id="adding_navigation" xml:base="file:///home/ochikvina/WORK/for_compare/trunk/jsf/docs/jsf_tools_tutorial/en/modules/adding_navigation.xml" xreflabel="adding_navigation"> + <?dbhtml filename="adding_navigation.html"?> + <chapterinfo> + <keywordset> + <keyword>JBoss Tools</keyword> + <keyword>JSF application</keyword> + <keyword>Java</keyword> + </keywordset> + </chapterinfo> + + <title>Adding Navigation to the Application</title> + + <para>In our simple application, the flow is defined as a single navigation rule connecting + two views (presentation files). At this point, we will create the placeholders for the + two JSP presentation files and then the navigation rule to connect them as views. Later, + we will complete the coding for the JSP presentation files. We can do all of this in the + Diagram mode of the configuration file editor.</para> + <section id="AddingTwoViewsJSPPages"> + <?dbhtml filename="AddingTwoViewsJSPPages.html"?> + <title>Adding Two Views (JSP Pages)</title> + <itemizedlist> + <listitem> + <para>Right-click anywhere on the diagram and select <emphasis> + <property moreinfo="none">New View...</property> + </emphasis> from the pop-up menu</para> + </listitem> + <listitem> + <para>In the dialog box, type <emphasis> + <property moreinfo="none">pages/inputname</property> + </emphasis> as the value for From-view-id</para> + </listitem> + <listitem> + <para>Leave everything else as is</para> + </listitem> + <listitem> + <para>Click <emphasis> + <property moreinfo="none">Finish</property> + </emphasis></para> + <para>If you look in the Package Explorer view you should see a <emphasis> + <property moreinfo="none">pages</property> + </emphasis> folder under WebContent. Opening it will reveal the JSP file you + just created</para> + </listitem> + <listitem> + <para>Back on the diagram, right-click anywhere and select <emphasis> + <property moreinfo="none">New View...</property> + </emphasis> from the pop-up menu</para> + </listitem> + <listitem> + <para>In the dialog box, type <emphasis> + <property moreinfo="none">pages/greeting</property> + </emphasis> as the value for From-view-id</para> + </listitem> + <listitem> + <para>Leave everything else as is</para> + </listitem> + <listitem> + <para>Click <emphasis> + <property moreinfo="none">Finish</property> + </emphasis></para> + </listitem> + </itemizedlist> + + </section> + <section id="CreatingTheTransitionNavigationRule"> + <?dbhtml filename="CreatingTheTransitionNavigationRule.html"?> + <title>Creating the Transition (Navigation Rule)</title> + <itemizedlist> + <listitem> + <para>In the diagram, select the connection icon third from the top along + the upper left side of the diagram</para> + </listitem> + </itemizedlist> + <figure float="0"> + <title>Connection Icon</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/jsf_application/jsf_application_3.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + <para>to get an arrow cursor with a two-pronged plug at the arrow's bottom.</para> + <itemizedlist> + <listitem> + <para>Click on the <emphasis> + <property moreinfo="none">pages/inputname</property> + </emphasis> page icon and then click on the <emphasis> + <property moreinfo="none">pages/greeting</property> + </emphasis> page icon</para> + </listitem> + + </itemizedlist> + <para>A transition should appear between the two icons.</para> + <figure float="0"> + <title>Transition Between Two Icons</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/jsf_application/jsf_application_4.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + <itemizedlist> + <listitem> + <para>Select <emphasis> + <property moreinfo="none">File > Save</property> + </emphasis> from the menu bar</para> + </listitem> + </itemizedlist> + </section> + +</chapter> + +<chapter id="adding_managed_bean" xml:base="file:///home/ochikvina/WORK/for_compare/trunk/jsf/docs/jsf_tools_tutorial/en/modules/adding_managed_bean.xml" xreflabel="adding_managed_bean"> + <?dbhtml filename="adding_managed_bean.html"?> + <chapterinfo> + <keywordset> + <keyword>JBoss Developer Studio</keyword> + <keyword>JSF application</keyword> + <keyword>Java</keyword> + </keywordset> + </chapterinfo> + + <title>Adding a Managed Bean to the Application</title> + <para>To store data in the application, we will use a managed bean.</para> + <itemizedlist> + <listitem> + <para>Click on the <emphasis> + <property moreinfo="none">Tree</property> + </emphasis> tab at the bottom of the editing window</para> + </listitem> + <listitem> + <para>Select the <emphasis> + <property moreinfo="none">Managed Beans</property> + </emphasis> node and then click the <emphasis> + <property moreinfo="none">Add...</property> + </emphasis> button displayed along the right side of the editor window</para> + </listitem> + <listitem> + <para>Type in <emphasis> + <property moreinfo="none">jsfHello.PersonBean</property> + </emphasis> for Class and <emphasis> + <property moreinfo="none">personBean</property> + </emphasis> for Name. Leave Scope as is and Generate Source Code as is + (checked)</para> + </listitem> + <listitem> + <para>Click <emphasis> + <property moreinfo="none">Finish</property> + </emphasis></para> + </listitem> + <listitem> + <para>personBean will now be selected and three sections of information: <emphasis> + <property moreinfo="none">Managed Bean</property> + </emphasis>, <emphasis> + <property moreinfo="none">Properties</property> + </emphasis>, and <emphasis> + <property moreinfo="none">Advanced</property> + </emphasis>, will be displayed about it. Under the Properties section, click the <emphasis> + <property moreinfo="none">Add...</property> + </emphasis> button</para> + </listitem> + <listitem> + <para>Type in <emphasis> + <property moreinfo="none">name</property> + </emphasis> for Property-Name. Leave everything else as is. (When Property- + Class is not filled in, String is the assumed type)</para> + </listitem> + <listitem> + <para>Click <emphasis> + <property moreinfo="none">Finish</property> + </emphasis></para> + </listitem> + <listitem> + <para>Select the <emphasis> + <property moreinfo="none">personBean</property> + </emphasis> node in the tree</para> + </listitem> + </itemizedlist> + <para>You should see this now:</para> + <figure float="0"> + <title>Tree View in Config Editor</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/jsf_application/jsf_application_5.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + <itemizedlist> + <listitem> + <para>Select <emphasis> + <property moreinfo="none">File > Save</property> + </emphasis> from the menu bar</para> + </listitem> + </itemizedlist> + <para>You have now registered the <emphasis> + <property moreinfo="none">managed bean</property> + </emphasis> and created a <emphasis> + <property moreinfo="none">stub-coded class</property> + </emphasis> file for it.</para> + + </chapter> + +<chapter id="jsp_view_files" xml:base="file:///home/ochikvina/WORK/for_compare/trunk/jsf/docs/jsf_tools_tutorial/en/modules/jsp_view_files.xml" xreflabel="jsp_view_files"> + <?dbhtml filename="jsp_view_files.html"?> + <chapterinfo> + <keywordset> + <keyword>JBoss Tools</keyword> + <keyword>JSF application</keyword> + <keyword>Java</keyword> + </keywordset> + </chapterinfo> + + <title>Editing the JSP View Files</title> + + <para>Now we will finish editing the JSP files for our two "views" using + JSP Visual Page.</para> + <section id="Inputname.jsp"> + <title>inputname.jsp</title> + <itemizedlist> + <listitem> + <para>Click on the <emphasis> + <property moreinfo="none">Diagram</property> + </emphasis> tab for the configuration file editor</para> + </listitem> + <listitem> + <para>Open the editor for this first JSP file by double-clicking on the <emphasis> + <property moreinfo="none">/pages/inputname. jsp</property> + </emphasis> icon</para> + </listitem> + </itemizedlist> + + <para>The Visual Page Editor will open in a screen split between source code along the + top and a WYSIWIG view along the bottom:</para> + <figure float="0"> + <title>Visual Page Editor</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/jsf_application/jsf_application_6.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + <para>Some JSF code is already in the file, because we have chosen a template to create + a page.</para> + <itemizedlist> + <listitem> + <para>Select the <emphasis> + <property moreinfo="none">Visual</property> + </emphasis> tab, so we can work with the editor completely in its WYSIWYG + mode</para> + </listitem> + <listitem> + <para>To the right of the editor, in the JBoss Tools Palette, expand the <emphasis> + <property moreinfo="none">JSF HTML</property> + </emphasis> palette folder by selecting it</para> + </listitem> + </itemizedlist> + <figure float="0"> + <title>JBoss Tools Palette</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/jsf_application/jsf_application_7.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + <itemizedlist> + <listitem> + <para>Click on <emphasis> + <property moreinfo="none">form</property> + </emphasis> within this folder, drag the cursor over to the editor, and drop + it inside the red box in the editor</para> + </listitem> + <listitem> + <para>Another red box will appear inside the first red box</para> + </listitem> + <listitem> + <para>Right-click on the innermost box and select <emphasis role="bold"> + <property moreinfo="none"><h:form></property> + </emphasis> Attributes from the menu</para> + </listitem> + <listitem> + <para>In the value field next to id, type <emphasis> + <property moreinfo="none">greeting</property> + </emphasis> and click on the <emphasis> + <property moreinfo="none">Close</property> + </emphasis> button</para> + </listitem> + <listitem> + <para>Type "Please enter name:" inside the boxes</para> + </listitem> + <listitem> + <para>Select <emphasis> + <property moreinfo="none">inputText</property> + </emphasis> within the JSF HTML palette folder and drag it into the + innermost box in the editor after "Please enter + name:"</para> + </listitem> + <listitem> + <para>In the attributes dialog, click in the <emphasis> + <property moreinfo="none">value</property> + </emphasis> field next to the value attribute and click on the <property moreinfo="none">... + </property>button</para> + </listitem> + <listitem> + <para>Then, select the <emphasis> + <property moreinfo="none">Managed Beans > personBean > name</property> + </emphasis> node and click on the <emphasis> + <property moreinfo="none">Ok</property> + </emphasis> button</para> + </listitem> + <listitem> + <para>Back in the attributes dialog, select the <emphasis> + <property moreinfo="none">Advanced</property> + </emphasis> tab, type in <emphasis> + <property moreinfo="none">name</property> + </emphasis> as the value for the <emphasis role="italic"> + <property moreinfo="none">"id"</property> + </emphasis> attribute, and then click on the <emphasis> + <property moreinfo="none">Finish</property> + </emphasis> button</para> + </listitem> + <listitem> + <para>Select <emphasis> + <property moreinfo="none">commandButton</property> + </emphasis> within the JSF HTML palette folder and drag it into the + innermost box in the editor after the input box</para> + </listitem> + <listitem> + <para>In the attributes dialog, click in the value field next to the <emphasis role="italic"> + <property moreinfo="none">"action"</property> + </emphasis> attribute and click on the <property moreinfo="none">... + </property>button</para> + </listitem> + <listitem> + <para>Then, select the <emphasis> + <property moreinfo="none">View Actions > greeting</property> + </emphasis> node and click on the <emphasis> + <property moreinfo="none">OK</property> + </emphasis> button</para> + </listitem> + <listitem> + <para>Back in the attributes dialog box, type in "Say Hello" + as the value for the value attribute ("Say Hello") and + then click on the <emphasis> + <property moreinfo="none">Finish</property> + </emphasis> button</para> + </listitem> + </itemizedlist> + <para>The source coding should be something like this now:</para> + <programlisting format="linespecific" role="XML"><![CDATA[<%@ taglib uri="http://java.sun.com/jsf/html" prefix="h" %> +<%@ taglib uri="http://java.sun.com/jsf/core" prefix="f" %> +<html> +<head> +<title></title> +</head> +<body> +<f:view> +<h:form id="greeting"> +<para>Please enter a name:</para> +<h:inputText id="name" value="#{personBean.name}"/> +<h:commandButton value=" Say Hello " action="greeting"/> +</h:form> +</f:view> +</body> +</html> +]]></programlisting> + <para>The editor should look like this:</para> + <figure float="0"> + <title>Visual Page Editor</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/jsf_application/jsf_application_8.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + <itemizedlist> + <listitem> + <para>Save the file by selecting <emphasis> + <property moreinfo="none">File > Save</property> + </emphasis> from the menu bar</para> + </listitem> + </itemizedlist> + </section> + <section id="Greeting.jsp"> + <title>greeting.jsp</title> + <itemizedlist> + <listitem> + <para>Click on the <emphasis> + <property moreinfo="none">faces-config.xml</property> + </emphasis> tab to bring the diagram back</para> + </listitem> + <listitem> + <para>Open the editor for the second file by double-clicking on the <emphasis> + <property moreinfo="none">/pages/greeting.jsp</property> + </emphasis> icon</para> + </listitem> + <listitem> + <para>Select the <emphasis> + <property moreinfo="none">Visual</property> + </emphasis> tab, so we can work with the editor completely in its WYSIWYG + mode</para> + </listitem> + <listitem> + <para>Type "Hello "(note space after Hello) into the + box</para> + </listitem> + <listitem> + <para>Select <emphasis> + <property moreinfo="none">outputText</property> + </emphasis> within the JSF HTML palette folder and drag it into the + innermost box in the editor after "Hello"</para> + </listitem> + <listitem> + <para>In the attributes dialog, click in <emphasis> + <property moreinfo="none">value</property> + </emphasis> field next to the value attribute and click on the + <property moreinfo="none">...</property> (Browse) button</para> + </listitem> + <listitem> + <para>Then, select the <emphasis> + <property moreinfo="none">Managed Beans > personBean > name</property> + </emphasis> node, click on the <emphasis> + <property moreinfo="none">Ok</property> + </emphasis> button, and then click on the <emphasis> + <property moreinfo="none">Finish</property> + </emphasis> button</para> + </listitem> + <listitem> + <para>Right after the output field, type an <emphasis> + <property moreinfo="none">exclamation point</property> + </emphasis> (<emphasis> + <property moreinfo="none">!</property> + </emphasis>)</para> + </listitem> + </itemizedlist> + <para>The source coding should be something like this now:</para> + <programlisting format="linespecific" role="XML"><![CDATA[<%@ taglib uri="http://java.sun.com/jsf/html" prefix="h" %> +<%@ taglib uri="http://java.sun.com/jsf/core" prefix="f" %> +<html> +<head> +<title></title> +</head> +<body> +<f:view> +Hello <h:outputText value="#{personBean.name}"/>! +</f:view> +</body> +</html> +]]></programlisting> + <itemizedlist> + <listitem> + <para>Save the file</para> + </listitem> + </itemizedlist> + </section> + </chapter> + +<chapter id="start_page" xml:base="file:///home/ochikvina/WORK/for_compare/trunk/jsf/docs/jsf_tools_tutorial/en/modules/start_page.xml" xreflabel="start_page"> + <?dbhtml filename="start_page.html"?> + <chapterinfo> + <keywordset> + <keyword>JBoss Tools</keyword> + <keyword>JSF application</keyword> + <keyword>Java</keyword> + </keywordset> + </chapterinfo> + + <title>Creating the Start Page</title> + <para>You also need to create a start page as an entry point into the application.</para> + <itemizedlist> + <listitem> + <para>In the Package Explorer view to the left, right-click <emphasis> + <property moreinfo="none">jsfHello > WebContent</property> + </emphasis> and select <emphasis> + <property moreinfo="none">New > JSP File</property> + </emphasis></para> + </listitem> + <listitem> + <para>For Name type in <emphasis> + <property moreinfo="none">index</property> + </emphasis>, for Template select <emphasis> + <property moreinfo="none">JSPRedirect</property> + </emphasis> and click <emphasis> + <property moreinfo="none">Finish</property> + </emphasis></para> + </listitem> + </itemizedlist> + <para>A JSP editor will open up on the newly created file.</para> + + <itemizedlist> + <listitem> + <para>In the Source part of the split screen, type <emphasis> + <property moreinfo="none">/pages/inputname.jsf</property> + </emphasis> in between the quotes for the page attribute</para> + </listitem> + </itemizedlist> + <para>The source coding should look like this now:</para> + <programlisting format="linespecific" role="XML"><![CDATA[<!doctype html public "-//w3c//dtd html 4.0 transitional//en"> +<html> +<head></head> +<body> +<jsp:forward page="/pages/inputname.jsf" /> +</body> +</html> +]]></programlisting> + + <para>Note the <emphasis> + <property moreinfo="none">.jsf</property> + </emphasis> extension for the file name. This is a mapping defined in the web.xml file + for the project for invoking <property moreinfo="none">JavaServer Faces</property> when you run the + application.</para> + <itemizedlist> + <listitem> + <para>Select<emphasis> + <property moreinfo="none"> File > Save</property> + </emphasis> from the menu bar</para> + </listitem> + </itemizedlist> + </chapter> + +<chapter id="running_application" xml:base="file:///home/ochikvina/WORK/for_compare/trunk/jsf/docs/jsf_tools_tutorial/en/modules/running_application.xml" xreflabel="running_application"> + <?dbhtml filename="running_application.html"?> + <chapterinfo> + <keywordset> + <keyword>JBoss Tools</keyword> + <keyword>JSF application</keyword> + <keyword>Java</keyword> + </keywordset> + </chapterinfo> + + <title>Running the Application</title> + <para>Everything is now ready for running our application by using the JBoss engine. For + controlling JBoss server there is JBoss Server view:</para> + <figure float="0"> + <title>JBoss Server View</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/jsf_application/jsf_application_9.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + <itemizedlist> + <listitem> + <para>Start up JBoss by clicking on the icon in JBoss Server view. (If JBoss is + already running, stop it by clicking on the red icon and then start it again. + Remember, the JSF run-time requires restarting the servlet engine when any + changes have been made.) After the messages in the Console tabbed view stop + scrolling, JBoss is available</para> + </listitem> + + <listitem> + <para>Click the Run icon or right click your project folder and select <emphasis> + <property moreinfo="none">Run As > Run on Server</property> + </emphasis>:</para> + </listitem> + </itemizedlist> + <figure float="0"> + <title>Run Icon</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/jsf_application/jsf_application_10.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + <para>This is the equivalent of launching the browser and typing <emphasis> + <property moreinfo="none">http://localhost:8080/jsfHello</property> + </emphasis> into your browser. Our <property moreinfo="none">JSF application</property> should now + appear.</para> + </chapter> + +<chapter id="relevant_resources" xml:base="file:///home/ochikvina/WORK/for_compare/trunk/jsf/docs/jsf_tools_tutorial/en/modules/relevant_resources.xml" xreflabel="relevant_resources"> + <?dbhtml filename="relevant_resources.html"?> + <chapterinfo> + <keywordset> + <keyword>JBoss Tools</keyword> + <keyword>JSF application</keyword> + <keyword>Java</keyword> + </keywordset> + </chapterinfo> + + <title>Other Relevant Resources on the topic</title> + <para>JSF on Sun: <ulink url="http://java.sun.com/javaee/javaserverfaces/">JavaServer Faces + Technology</ulink></para> + <para>Core JSF: <ulink url="http://www.horstmann.com/corejsf/">Core JavaServer Faces</ulink></para> + <para>API: <ulink url="http://java.sun.com/javaee/javaserverfaces/1.1/docs/api/index.html"><diffmk:wrapper diffmk:change="changed">JSF + API</diffmk:wrapper></ulink></para> + <para>JSF Tags: <ulink url="http://www.horstmann.com/corejsf/jsf-tags.html"><diffmk:wrapper diffmk:change="changed">JSF Core + Tags</diffmk:wrapper></ulink></para> + <para>HTML Tags Reference: <ulink url="http://www.exadel.com/tutorial/jsf/jsftags-guide.html"><diffmk:wrapper diffmk:change="changed">JSF HTML Tags Reference</diffmk:wrapper></ulink></para> + <para>JSF Central: <ulink url="http://www.jsfcentral.com/"><diffmk:wrapper diffmk:change="changed">JSF Central - Your JavaServer Faces + Community</diffmk:wrapper></ulink></para> + <para>FAQ: <ulink url="http://wiki.java.net/bin/view/Projects/JavaServerFacesSpecFaq"><diffmk:wrapper diffmk:change="changed">JSF + FAQ</diffmk:wrapper></ulink></para> + <para>Download: <ulink url="http://java.sun.com/javaee/javaserverfaces/download.html"><diffmk:wrapper diffmk:change="changed">JavaServer + Faces Technology - Download</diffmk:wrapper></ulink></para> + + <para diffmk:change="added"><diffmk:wrapper diffmk:change="added">In summary, with this tutorial you should now know how to organize JSF sample application + using the wizards provided by </diffmk:wrapper><property diffmk:change="added" moreinfo="none"><diffmk:wrapper diffmk:change="added">JBoss Tools</diffmk:wrapper></property><diffmk:wrapper diffmk:change="added">, configure its stuff and + finally run it on the </diffmk:wrapper><property diffmk:change="added" moreinfo="none"><diffmk:wrapper diffmk:change="added">JBoss Server</diffmk:wrapper></property><diffmk:wrapper diffmk:change="added">.</diffmk:wrapper></para> + + <para diffmk:change="added"><diffmk:wrapper diffmk:change="added">Find out more features on JSF tooling in our </diffmk:wrapper><ulink diffmk:change="added" url="../../jsf_tools_ref_guide/html_single/index.html"><diffmk:wrapper diffmk:change="added">JSF Tools + Reference Guide</diffmk:wrapper></ulink><diffmk:wrapper diffmk:change="added">. If you have questions and suggestions, please refer to </diffmk:wrapper><ulink diffmk:change="added" url="http://www.jboss.com/index.html?module=bb&op=viewforum&f=201"><diffmk:wrapper diffmk:change="added">JBoss + Tools Forum</diffmk:wrapper></ulink><diffmk:wrapper diffmk:change="added">.</diffmk:wrapper></para> +</chapter> + +</book> Modified: branches/jbosstools-3.0.0.CR1/jsf/docs/jsf_tools_tutorial/en/modules/relevant_resources.xml =================================================================== --- branches/jbosstools-3.0.0.CR1/jsf/docs/jsf_tools_tutorial/en/modules/relevant_resources.xml 2008-12-19 19:26:54 UTC (rev 12774) +++ branches/jbosstools-3.0.0.CR1/jsf/docs/jsf_tools_tutorial/en/modules/relevant_resources.xml 2008-12-19 19:29:02 UTC (rev 12775) @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="UTF-8"?> -<chapter id="relevant_resources" xreflabel="relevant_resources"> +<chapter id="relevant_resources" xreflabel="relevant_resources" role="updated"> <?dbhtml filename="relevant_resources.html"?> <chapterinfo> <keywordset>

15 years, 4 months

1
0
0 / 0

JBoss Tools SVN: r12774 - in branches/jbosstools-3.0.0.CR1/jsf/docs/jsf_tools_ref_guide/en: modules and 1 other directory.

by jbosstools-commits＠lists.jboss.org

Author: smukhina Date: 2008-12-19 14:26:54 -0500 (Fri, 19 Dec 2008) New Revision: 12774 Added: branches/jbosstools-3.0.0.CR1/jsf/docs/jsf_tools_ref_guide/en/master_output.xml Modified: branches/jbosstools-3.0.0.CR1/jsf/docs/jsf_tools_ref_guide/en/master.xml branches/jbosstools-3.0.0.CR1/jsf/docs/jsf_tools_ref_guide/en/modules/jsf_project_verification.xml branches/jbosstools-3.0.0.CR1/jsf/docs/jsf_tools_ref_guide/en/modules/managed_beans.xml Log: https://jira.jboss.org/jira/browse/JBDS-324 docs from trunk are added to branch master_output - the file to build guide versions with highlighted diff markers Modified: branches/jbosstools-3.0.0.CR1/jsf/docs/jsf_tools_ref_guide/en/master.xml =================================================================== --- branches/jbosstools-3.0.0.CR1/jsf/docs/jsf_tools_ref_guide/en/master.xml 2008-12-19 19:21:12 UTC (rev 12773) +++ branches/jbosstools-3.0.0.CR1/jsf/docs/jsf_tools_ref_guide/en/master.xml 2008-12-19 19:26:54 UTC (rev 12774) @@ -41,7 +41,7 @@ <holder>JBoss, a division of Red Hat Inc.</holder> </copyright> <releaseinfo> - Version: 3.0.0.beta1 + Version: 3.0.0.CR1 </releaseinfo> <abstract> Added: branches/jbosstools-3.0.0.CR1/jsf/docs/jsf_tools_ref_guide/en/master_output.xml =================================================================== --- branches/jbosstools-3.0.0.CR1/jsf/docs/jsf_tools_ref_guide/en/master_output.xml (rev 0) +++ branches/jbosstools-3.0.0.CR1/jsf/docs/jsf_tools_ref_guide/en/master_output.xml 2008-12-19 19:26:54 UTC (rev 12774) @@ -0,0 +1,1262 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" +"http://www.docbook.org/xml/4.3/docbookx.dtd" + +[ +<!ENTITY introduction SYSTEM "modules/introduction.xml"> +<!ENTITY projects SYSTEM "modules/projects.xml"> +<!ENTITY editors SYSTEM "modules/editors.xml"> +<!ENTITY modules SYSTEM "modules/modules.xml"> +<!ENTITY code_generation SYSTEM "modules/code_generation.xml"> +<!ENTITY config_file_debugger SYSTEM "modules/config_file_debugger.xml"> +<!ENTITY page_links_recognizer SYSTEM "modules/page_links_recognizer.xml"> +<!ENTITY project_verification SYSTEM "modules/project_verification.xml"> +<!ENTITY rel_resources_links SYSTEM "modules/rel_resources_links.xml"> + +<!ENTITY seamlink "../../seam/html_single/index.html"> +<!ENTITY aslink "../../as/html_single/index.html"> +<!ENTITY esblink "../../esb_ref_guide/html_single/index.html"> +<!ENTITY gsglink "../../GettingStartedGuide/html_single/index.html"> +<!ENTITY hibernatelink "../../hibernatetools/html_single/index.html"> +<!ENTITY jbpmlink "../../jbpm/html_single/index.html"> +<!ENTITY jsflink "../../jsf/html_single/index.html"> +<!ENTITY jsfreflink "../../jsf_tools_ref_guide/html_single/index.html"> +<!ENTITY jsftutoriallink "../../jsf_tools_tutorial/html_single/index.html"> +<!ENTITY strutsreflink "../../struts_tools_ref_guide/html_single/index.html"> +<!ENTITY strutstutoriallink "../../struts_tools_tutorial/html_single/index.html"> +<!ENTITY migrationlink "../../Exadel-migration/html_single/index.html"> + +]><book xmlns:diffmk="http://diffmk.sf.net/ns/diff"> + <bookinfo> + <title>Struts Tools Reference Guide</title> + + <author><firstname>Anatoly</firstname><surname>Fedosik</surname></author> + <author><firstname>Olga</firstname><surname>Chikvina</surname></author> + <author><firstname>Svetlana</firstname><surname>Mukhina</surname><email>smukhina(a)exadel.com</email></author> + + <pubdate>April 2008</pubdate> + <copyright> + <year>2007</year> + <year>2008</year> + <holder>JBoss, a division of Red Hat Inc.</holder> + </copyright> + <releaseinfo><diffmk:wrapper diffmk:change="changed"> + Version: 3.0.0.CR1 + </diffmk:wrapper></releaseinfo> + +<abstract> + <title></title> + <para> + <ulink url="http://download.jboss.org/jbosstools/nightly-docs/en/struts_tools_ref_gui...">PDF version</ulink> + </para> +</abstract> + + + </bookinfo> + + <toc></toc> + + +<chapter id="intoduction" xml:base="file:///home/ochikvina/WORK/for_compare/trunk/struts/docs/struts_tools_ref_guide/en/modules/introduction.xml"> + <?dbhtml filename="introduction.html"?> + + <chapterinfo> + <keywordset> + <keyword>JBoss Developer Studio</keyword> + <keyword>Eclipse</keyword> + <keyword>Java</keyword> + <keyword>JBoss</keyword> + </keywordset> + </chapterinfo> + + <title>Introduction</title> + + <para>If you prefer to develop web applications using Struts technology JBoss Tools also meet + your needs. The professional developer toolset provides all necessary editors and wizards + for creating Struts resources that enhances the process of building high-quality web + applications.</para> + <note> + <title>Note:</title> + <para>Note that JBoss Tools support the Struts 1.1, 1.2.x versions.</para> + </note> + + <para>In this guide you will learn how to take advantage of Struts support that <property moreinfo="none">JBoss Tools</property> + provide.</para> + + <section id="struts_key_features"> + <title>Key Features of Struts Tools</title> + + <para>For a start, we propose you to look through the table of main features of Struts + Tools:</para> + + <table> + + <title>Key Functionality for Struts Tools</title> + <tgroup cols="3"> + + <colspec align="left" colnum="1" colwidth="2*"></colspec> + <colspec colnum="2" colwidth="4*"></colspec> + <colspec align="left" colnum="3" colwidth="2*"></colspec> + + <thead> + <row> + <entry>Feature</entry> + <entry>Benefit</entry> + <entry>Chapter</entry> + </row> + </thead> + <tbody> + <row> + <entry><para>Struts Support</para></entry> + <entry><para>Step-by-step wizards for creating a new struts project with a number + of predefined templates, importing existing ones and adding struts + capabilities to non-struts web projects.</para></entry> + <entry> + <link linkend="projects">struts support</link> + </entry> + </row> + + <row> + <entry><para>Support for Struts Configuration File</para></entry> + <entry><para>Working on file using three modes: diagram, tree and source. + Synchronization between the modes and full control over the code. Easy + moving around the diagram using the Diagram Navigator. Working with + struts projects that have multiple modules. Possibility to use Struts + configuration file debugger allowing to set break points on struts + diagram and then launch the server in debug mode.</para></entry> + <entry> + <link linkend="struts_config_editor">graphical editor for struts</link> + <link linkend="config_file_debugger">configuration file debugger</link> + </entry> + </row> + + <row> + <entry><para>Support for Struts modules</para></entry> + <entry><para>A Struts module (struts-config.xml) is automatically created while + creating a new project. There is also possibility to add new ones or edit + already existing modules in your existing project or while importing Struts project.</para></entry> + <entry> + <link linkend="modules">modules</link> + </entry> + </row> + + <row> + <entry><para>Verification and Validation</para></entry> + <entry><para>All occuring errors will be immediately reported by verification + feature, no matter in what view you are working. Constant validation and + errors checking allows to catch many of the errors during development + process that significantly reduces development time.</para></entry> + <entry> + <link linkend="project_verification">verification and validation</link> + </entry> + + </row> + </tbody> + </tgroup> + </table> + + </section> + + <section> + <title>Other relevant resources on the topic</title> + + <para>All JBoss Developer Studio/JBoss Tools documentation you can find <ulink url="http://docs.jboss.org/tools/">here</ulink>.</para> + <para>The latest documentation builds are available <ulink url="http://download.jboss.org/jbosstools/nightly-docs/">here</ulink>.</para> + + </section> + +</chapter> + + +<chapter id="projects" xml:base="file:///home/ochikvina/WORK/for_compare/trunk/struts/docs/struts_tools_ref_guide/en/modules/projects.xml"> + <?dbhtml filename="projects.html"?> + + <chapterinfo> + <keywordset> + <keyword>JBoss Developer Studio</keyword> + <keyword>Eclipse</keyword> + <keyword>Java</keyword> + <keyword>JBoss</keyword> + </keywordset> + </chapterinfo> + + <title>Projects</title> + + <para>JBoss Tools provide the following functionality when working with Struts:</para> + + <itemizedlist> + <listitem> + <para>Create new <property moreinfo="none">Struts projects</property></para> + </listitem> + <listitem> + <para>Import (open) existing Struts projects. You can import any project + structure</para> + </listitem> + <listitem> + <para>Add <property moreinfo="none">Struts capabilities</property> to any existing Eclipse + project</para> + </listitem> + <listitem> + <para>Import and add Struts capabilities to any existing project created outside + Eclipse.</para> + </listitem> + </itemizedlist> + <para>Now, we'll focus on all these points more fully.</para> + + <section id="CreatingANewStrutsProjec745t"> + + <title>Creating a New Struts Project</title> + + + <para>JBoss Tools provides a New Struts Project Wizard that radically simplifies the process + for getting started with a new Struts project. You just need to follow these steps:</para> + <itemizedlist> + <listitem> + <para>Select<emphasis> + <property moreinfo="none">File > New > Project...</property> + </emphasis> from the menu bar. Then, select <emphasis> + <property moreinfo="none">JBoss Tools Web > Struts > Struts Project</property> + </emphasis> in this dialog box. Click <emphasis> + <property moreinfo="none">Next</property>: </emphasis></para> + </listitem> + </itemizedlist> + <figure float="0"> + <title>Selecting Struts Wizard</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_2.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + <itemizedlist> + <listitem> + <para>On this form, provide the <property moreinfo="none">Project Name</property>. You can also + select where to create the project or use the default path.</para> + <para>Next to <property moreinfo="none">Struts Environment</property> set which Struts version to + use.</para> + </listitem> + </itemizedlist> + + <figure float="0"> + <title>Creating Struts Project</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_3.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <tip> + <title>Tip:</title> + <para>Don't put spaces in project names since some OS could experience problems + with their processing and searching these files.</para> + </tip> + + <para>You can select the KickStart template, then the project created will include a simple + Hello World type application that is ready to run.</para> + + <figure float="0"> + <title>Choosing Struts Template </title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_3_1.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <itemizedlist> + <listitem> + <para>Next, you register this application with the current servlet container defined + for your workspace (JBoss AS, by default) in order to allow you to test your + application more easily while still developing it. A new entry will be added in + the servlet container configuration file to enable running the application + in-place (called null deployment or link deployment). Uncheck the <emphasis role="italic"> + <property moreinfo="none">"Target Server"</property> + </emphasis> check box if for some reason you don't want to register + your application at this point.</para> + </listitem> + </itemizedlist> + <figure float="0"> + <title>Registering The Project at Server</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_4.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + <itemizedlist> + <listitem> + <para>On the next form, you can select the TLD files to include in this + project:</para> + </listitem> + </itemizedlist> + <figure float="0"> + <title>Selecting Tag Libraries</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_5.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>After the project is created, you should have the following project structure (if you + used the KickStart template):</para> + + <figure float="0"> + <title>Project Structure</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_6.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <tip> + <title>Tip:</title> + <para>If you want to hide the jar files from Web App Libraries in view, select the + down-pointing arrow in the upper right corner, select + <emphasis>Filters...</emphasis>, check the box next to Name filter patterns + (matching names will be hidden), and type *.jar into the field. Then, click OK. + </para> + </tip> + </section> + <section id="ImportingAnExistingStrutsProjectWithAnyStructure9653"> + + <title>Importing an Existing Struts Project with Any Structure</title> + + <para>For detailed information on migration projects to JBoss Developer Studio see <ulink url="../../Exadel-migration/html_single/index.html">Migration Guide</ulink>.</para> + + </section> + <section id="AddingStrutsCapabilityToAnExistingWebApplication532"> + + <title>Adding Struts Capability to an Existing Web Application</title> + + <para>Here, we'll consider how to add Struts functionality (Struts libraries, tag + libraries and a Struts configuration file) to any existing Web application project in + your Eclipse workspace.</para> + + <para>By adding a Struts Nature to your project, you can now edit files using JBoss Tools + editors, such as the <link linkend="struts_config_editor">Struts configuration + editor</link> and the JBoss Tools JSP editor. To take advantage of this just right-click + the project and select <emphasis> + <property moreinfo="none">JBoss Tools > Add Struts Capabilities</property> + </emphasis> from the context menu. This will start the process of adding all necessary + libraries and files to make a Web Struts project from your one.</para> + + <figure float="0"> + <title>Adding Struts Capabilities</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_7.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>In the wizard you should point to location of your deployment descriptor file web.xml + and name of the project.</para> + + <figure float="0"> + <title>Choosing Project Location</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_8.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + <para>After hitting <emphasis> + <property moreinfo="none">Next</property>, </emphasis> you will see the following screen. This + screen simply means that you need to add at least one Struts module to your project to + make this project a Struts project. Adding a Struts module means that a new + struts-config.xml will be added to your project and registered in the web.xml file. In + addition, all required Struts libraries will be added. To add a Struts module, select + the <emphasis> + <property moreinfo="none">Add Struts Support</property> + </emphasis> button.</para> + <figure float="0"> + <title>Project Modules</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_9.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>Here you can select what Struts <property moreinfo="none">Version</property>, <property moreinfo="none">Servlet + Class</property>, <property moreinfo="none">URL Pattern</property> and <property moreinfo="none">TLD</property>s to add + to this project.</para> + + <figure float="0"> + <title>Selecting Struts Support Options</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_10.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>When done, you will see the default Struts module configuration information. See how + to Edit <link linkend="modules">Struts modules</link>.</para> + + <figure float="0"> + <title>Project Configuration Information</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_11.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>On the last screen you can set the different folders for your project as well as + register this application with a servlet container. If you want the libraries (.jar + files) will be automatically added to your project, click on the checkbox <emphasis> + <property moreinfo="none">Add Libraries</property>.</emphasis></para> + + <figure float="0"> + <title>Registering the Project at Server</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_12.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>When done, you can open end edit the struts-config.xml file using usefull Struts + configuration file editor provided by JBDS. (The Struts configuration is shown below in + the Tree viewer).</para> + + <figure float="0"> + <title>Struts-config.xml File</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_13.png" scale="75"></imagedata> + </imageobject> + </mediaobject> + </figure> + </section> + +</chapter> + + +<chapter id="editors" xml:base="file:///home/ochikvina/WORK/for_compare/trunk/struts/docs/struts_tools_ref_guide/en/modules/editors.xml"> + <?dbhtml filename="editors.html"?> + <chapterinfo> + <keywordset> + <keyword>JBoss Developer Studio</keyword> + <keyword>Eclipse</keyword> + <keyword>Struts Tools</keyword> + <keyword>Java</keyword> + <keyword>JBoss</keyword> + </keywordset> + </chapterinfo> + + <title>Editors</title> + <para>In this chapter we'll introduce you to featured graphical editors for specific + Struts files such as Struts Configuration files, Tiles files and Struts Validation files.</para> + <section id="struts_config_editor"> + + <title>Graphical Editor for Struts Configuration Files</title> + <para>First, let's dwell on the Struts Configuration file editor.</para> + <para>This editor has three views with different representation of <emphasis> + <property moreinfo="none">struts-config.xml</property>: </emphasis>Diagram, Tree and Source. The + views can be selected via the tabs at the bottom of the editor. Any changes made in one + view are immediately visible when you switch to any other view.</para> + + <para>Now, we'll consider every view in more detail.</para> + <section id="StrutsDiagramMode453"> + + <title>Diagram View</title> + + <para>The Diagram view graphically displays the Web flow of the application defined in + the Struts configuration file.</para> + + <figure float="0"> + <title>Diagram View</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_14.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>The Diagram view allows to edit navigation in your Struts application. Just by + right-clicking anywhere on the diagram, you can use a context menu to create the + building blocks of a Struts application:</para> + <itemizedlist> + <listitem> + <para>Actions</para> + </listitem> + <listitem> + <para>Global forwards</para> + </listitem> + <listitem> + <para>Global exceptions</para> + </listitem> + <listitem> + <para>JSP Pages</para> + </listitem> + </itemizedlist> + + <figure float="0"> + <title>Diagram Context Menu</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_15.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>Along the upper-left side of the editor is a stack of seven icons for changing the + behavior of the cursor in the diagram. </para> + + <figure float="0"> + <title>Editor Icons</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_16.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>The first icon switches to the default regular selection cursor, the second to the + marquee selection cursor and the third to the new connection cursor. The last four + icons switch the cursor to an insert cursor for each type of Struts build block + listed above (and in the order listed).</para> + + <para>For instance, clicking on the first of these four icons (the one with the gears) + will switch the cursor to insert actions. Clicking anywhere in the diagram with this + cursor has the same effect as right-click and selecting <emphasis> + <property moreinfo="none">Add > Action...</property> + </emphasis> from the context menu with the regular cursor active. It's just + more efficient to use this cursor if you're adding more than one action at + once.</para> + + + </section> + <section id="StrutsTreeMode42"> + + <title>Tree View</title> + + <para>The Tree view represents the different elements of the Struts application that are + organized into functional categories on the left-hand side and a form for editing + the properties of currently selected items on the right-hand side.</para> + + <figure float="0"> + <title>Tree View</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_17.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>You can also right-click on any node in the category tree and perform appropriate + operations through a context menu. For instance, by right-clicking on the + action-mappings category node, you can add new actions to the application.</para> + + <figure float="0"> + <title>Tree Context Menu</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_18.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + </section> + <section id="StrutsSourceMode9655"> + + <title>Source View</title> + + <para>In the Source view, you have complete editing control of the underlying XML + coding.</para> + + <figure float="0"> + <title>Source View</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_19.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>When working in Source view, you always have all the following features available:</para> + <itemizedlist> + <listitem> + <para>Content Assist</para> + </listitem> + <listitem> + <para>Open On Selection</para> + </listitem> + <listitem> + <para>File Folding</para> + </listitem> + </itemizedlist> + <para>You can take advantage of <ulink url="../../jsf/html_single/index.html#CodeAssistAndDynamicCodeAssist42BasedOnProjectData">code assist</ulink>.</para> + <figure float="0"> + <title>Code Assist</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_20.png" scale="85"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>The editor will also immediately flag any errors.</para> + + <figure float="0"> + <title>Errors in Source View</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_21.png" scale="85"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>Finally, you can use the Outline view with the editor to easily navigate through + the file.</para> + + <figure float="0"> + <title>Outline View</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_22.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>Find more information about editor features <ulink url="../../jsf/html_single/index.html#editors_features">here</ulink>.</para> + </section> + </section> + + <section id="GraphicalEditorForTilesFiles132"> + + <title>Graphical Editor for Tiles Files</title> + <para>Here, you'll know how to make use of the special graphical editor for Tiles configuration files.</para> + <para>The editor has three main views: Tree, Diagram and Source. + The views can be selected via the tabs at the bottom of the editor. Any changes made in + one view are immediately visible when you switch to any other view.</para> + + <para>Before we consider each view of the editor, let's look at the way of creating new Tiles files.</para> + <section id="CreateNewTilesFile1422"> + + <title>Create New Tiles File</title> + + <para>To create new Tiles files, right click any folder and select <emphasis> + <property moreinfo="none">New > Tiles File</property>. </emphasis></para> + <figure float="0"> + <title>Creating a New Tiles File</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_23.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + </section> + <section id="StrutsTreeView896"> + + <title>Tree View</title> + + <para>The Tree view represents the different elements of the Tiles file that are + organized into functional categories on the left-hand side and a form for editing + the properties of currently selected items on the right-hand side.</para> + <figure float="0"> + <title>Tree View</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_24.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>To edit the file, simply right click any node and select among the available + actions.</para> + <figure float="0"> + <title>Editing in Tiles Editor</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_25.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + </section> + <section id="StrutsDiagramView4643"> + + <title>Diagram View</title> + + <para>The Diagram view allows you to create complex Tiles files in the form of a + diagram.</para> + <figure float="0"> + <title>Diagram Mode</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_26.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>To create new definitions, simply right click anywhere in the diagram.</para> + <figure float="0"> + <title>Creating New Definition</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_27.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>You can also use the Diagram toolbar to make editing easier.</para> + <figure float="0"> + <title>Diagram Toolbar</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_28.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para> It contains four icons for changing the cursor state. The first one is the + default cursor state for selecting existing nodes. The second icon is marquee + selector. The third is used for creating new connections and the last one is for + adding definition template to the content.</para> + </section> + <section id="StrutsSource75"> + + <title>Source</title> + + <para>The other view of the <property moreinfo="none">Tiles editor</property> is the Source view that + gives you full control over the source. Any changes here will immediately appear in + other modes when you switch to them.</para> + + <para>When working in Source view, you always have all following features available:</para> + <itemizedlist> + <listitem> + <para>Content Assist</para> + </listitem> + <listitem> + <para>Open On Selection</para> + </listitem> + </itemizedlist> + + <figure float="0"> + <title>Source View</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_29.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + <para><ulink url="../../jsf/html_single/index.html#CodeAssistAndDynamicCodeAssist42BasedOnProjectData">Code + assist</ulink> is available in the Source mode.</para> + <figure float="0"> + <title>Code Assist</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_30.png" scale="85"></imagedata> + </imageobject> + </mediaobject> + </figure> + <para>Any errors are immediately reported as shown below:</para> + <figure float="0"> + <title>Errors Reporting</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_31.png" scale="75"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>You can also use the Outline view together with the editor's Source mode. + It provides an easier navigation through the file.</para> + <figure float="0"> + <title>Outline View</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_32.png" scale="85"></imagedata> + </imageobject> + </mediaobject> + </figure> + </section> + </section> + + <section id="GraphicalEditorForStrutsValidationFiles86"> + + <title>Graphical Editor for Struts Validation Files</title> + + <para>Providing full support for development Struts applications JBoss Tools comes with a + visual validation editor. To open the editor double-click on the validation file or if you don't have it create a new one.</para> + + <para>To create a new validation file, right click any folder in + Project Explorer and select <emphasis> + <property moreinfo="none">File > New > Other...</property> + </emphasis>from the context menu and then <emphasis> + <property moreinfo="none">JBoss Tools Web > Struts > Validation File</property>. </emphasis></para> + <figure float="0"> + <title>Creating New Validation File</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_33.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>The validation editor works with five modes: Formsets, Validators, Constants and + standard Tree and Source that you can easily switch over using tabs at the bottom of the + editor.</para> + <para>The Formsets view shows forms and their elements on the left side and the dialogue for + defining their validation rules on the right side.</para> + <figure float="0"> + <title>Formsets View</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_34.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>The Constants view let you set constant values for your validation rules.</para> + <figure float="0"> + <title>Constansts View</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_35.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>The validation file can also be viewed in a Tree view.</para> + <figure float="0"> + <title>Tree View</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_36.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>At any point you have full control over the source by switching to the Source view. + Any editing in this view will immediately be available in other views of the editor.</para> + <figure float="0"> + <title>Source View</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_37.png" scale="85"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>You can also open your own custom or Struts-standard <emphasis> + <property moreinfo="none">validation-rules.xml</property> + </emphasis> file.</para> + <para>The Validators view shows the validation rules for a selected validator. You can of + course add your own rules.</para> + <figure float="0"> + <title>Validators View</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_38.png" scale="75"></imagedata> + </imageobject> + </mediaobject> + </figure> + <para>Here are the validation rules shown in the Source mode.</para> + <figure float="0"> + <title>Validation Rules</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_39.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + </section> +</chapter> + + +<chapter id="modules" xml:base="file:///home/ochikvina/WORK/for_compare/trunk/struts/docs/struts_tools_ref_guide/en/modules/modules.xml"> + <?dbhtml filename="modules.html"?> + <chapterinfo> + <keywordset> + <keyword>JBoss Developer Studio</keyword> + <keyword>Eclipse</keyword> + <keyword>Struts Tools</keyword> + <keyword>Java</keyword> + <keyword>JBoss</keyword> + </keywordset> + </chapterinfo> + + <title>Modules</title> + + <para>JBoss Tools support working with Struts projects that have + multiple modules. You can easily do the following:</para> + <itemizedlist> + <listitem> + <para>Add new modules</para> + </listitem> + <listitem> + <para>Edit modules for an existing project or during Struts project + import</para> + </listitem> + </itemizedlist> + <para>Now, let's discuss this functionality in more detail.</para> + <section id="WhenImportingAStrutsProject432"> + + <title>When Importing a Struts Project</title> + + <para>During Struts project import, if the project has multiple modules, you + will see a screen with all existing modules. You can select each + module and edit its details.</para> + + <figure float="0"> + <title>Configuring Project Modules</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_40.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + </section> + <section id="EditingModulesInAnExistingProject1"> + + <title>Editing Modules in an Existing Project</title> + <para>To edit modules in an existing project, right click the project and + select <emphasis> + <property moreinfo="none">JBoss Tools > Modules Configuration</property>. + </emphasis></para> + <figure float="0"> + <title>Choosing Modules Configuration</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_41.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + <para>You will see the same screen as above where you will be able to select + a module and edit its details.</para> + <figure float="0"> + <title>Modules Configuration</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_42.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + </section> + <section id="AddingNewModules1"> + + <title>Adding New Modules</title> + + <para>Adding a new module is very simple. First switch to Web Project view. + Expand your project to the Configuration folder. Under that folder + you should see the current modules. Right click on Configuration and + select <emphasis> + <property moreinfo="none">New > Struts Config</property>. </emphasis></para> + <figure float="0"> + <title>Adding New Modules</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_43.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + <para>You will see the screen below. You can specify a new module name and + also add the new Struts configuration file to web.xml file.</para> + <figure float="0"> + <title>Adding New Modules</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_44.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + </section> +</chapter> + + +<chapter id="code_generation" xml:base="file:///home/ochikvina/WORK/for_compare/trunk/struts/docs/struts_tools_ref_guide/en/modules/code_generation.xml"> + <?dbhtml filename="code_generation.html"?> + + <chapterinfo> + <keywordset> + <keyword>JBoss Developer Studio</keyword> + <keyword>Eclipse</keyword> + <keyword>Struts Tools</keyword> + <keyword>Java</keyword> + <keyword>JBoss</keyword> + </keywordset> + </chapterinfo> + + <title>Code Generation</title> + + <para>JBoss Tools comes with a <property moreinfo="none">code generation</property> + feature. You can generate stub code for Struts Actions, FormBeans, Forwards + and Exceptions.</para> + + <para>The code generation that JBoss tooling provides is based on Velocity templates + which can be modified for your use. The templates are located at <emphasis> + <property moreinfo="none"> {JBossStudioHome} > templates > + codegeneration</property>. </emphasis></para> + + <para>There are a number of ways to invoke code generation. One is simply + right-clicking the Struts diagram and selecting <emphasis> + <property moreinfo="none">Generate Java Code....</property> + </emphasis></para> + + <figure float="0"> + <title>Selecting Generate Java Code</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_45.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>On this screen you can select for which elements to generate code. If you + select Next you will be able to specify more options for each of the + categories you selected.</para> + + <figure float="0"> + <title>Generate - Step 1</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_46.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <tip> + <title>Tip:</title> + <para>Please be careful not to override your existing files.</para> + </tip> + + <para>When generation is complete, a result window will appear letting you know how + many classes were generated:</para> + + <figure float="0"> + <title>Generation Finished</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_47.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>You don't always have to generate code for all elements at once. You + can invoke generation for just an individual Struts artifact as well. + Right-click an element on the diagram of the Struts configuration file and + select <emphasis> + <property moreinfo="none">Generate Java Code...</property> + </emphasis> from the context menu.</para> + + <figure float="0"> + <title>Generation For Individual Struts Artifact</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_48.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>The same can be done from within the Tree viewer for the editor of the Struts + configuration file.</para> + + <figure float="0"> + <title>Generation in Struts Config Editor</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_49.png"></imagedata> + </imageobject> + </mediaobject> + </figure> +</chapter> + +<chapter id="config_file_debugger" xml:base="file:///home/ochikvina/WORK/for_compare/trunk/struts/docs/struts_tools_ref_guide/en/modules/config_file_debugger.xml"> + <?dbhtml filename="config_file_debugger.html"?> + <chapterinfo> + <keywordset> + <keyword>JBoss Developer Studio</keyword> + <keyword>Eclipse</keyword> + <keyword>Struts Tools</keyword> + <keyword>Java</keyword> + <keyword>JBoss</keyword> + </keywordset> + </chapterinfo> + + <title>Struts Configuration File Debugger</title> + + <para>JBoss Tools come with <property moreinfo="none">Struts configuration file + debugger</property>. It allows you to set break points on Struts diagram and + then simply launch the server in debug mode.</para> + + <para>Simply right click an Action or a page and select Add <emphasis> + <property moreinfo="none">Breakpoint</property>. </emphasis></para> + <figure float="0"> + <title>Adding Breakpoint</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_50.png"></imagedata> + </imageobject> + </mediaobject> + </figure> +</chapter> + +<chapter id="page_links_recognizer" xml:base="file:///home/ochikvina/WORK/for_compare/trunk/struts/docs/struts_tools_ref_guide/en/modules/page_links_recognizer.xml"> + <?dbhtml filename="page_links_recognizer.html"?> + + <chapterinfo> + <keywordset> + <keyword>JBoss Developer Studio</keyword> + <keyword>Eclipse</keyword> + <keyword>Java</keyword> + <keyword>JBoss</keyword> + </keywordset> + </chapterinfo> + + <title>Customizable Page Links Recognizer</title> + + <para><property moreinfo="none">Custom page links</property> allow you to define custom Struts page + links that will be recognizable in the Struts application diagram. You can + define these links by selecting <emphasis> + <property moreinfo="none">Window > Preferences</property> + </emphasis> from the menu bar and then selecting <emphasis> + <property moreinfo="none">JBoss Tools > Web > Struts > Customization</property> + </emphasis> from the Preferences dialog box.</para> + <figure float="0"> + <title>Customization Panel</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/struts/struts_51.png"></imagedata> + </imageobject> + </mediaobject> + </figure> +</chapter> + +<chapter id="project_verification" xml:base="file:///home/ochikvina/WORK/for_compare/trunk/struts/docs/struts_tools_ref_guide/en/modules/project_verification.xml"> + <?dbhtml filename="project_verification.html"?> + <chapterinfo> + <keywordset> + <keyword>JBoss Developer Studio</keyword> + <keyword>Eclipse</keyword> + <keyword>Struts Tools</keyword> + <keyword>Java</keyword> + <keyword>JBoss</keyword> + </keywordset> + </chapterinfo> + + <title>Struts Project Verification</title> + + <para>In this section we'll consider one more functionality that JBoss Tools provide for Struts + projects, namely adjusting projects verification.</para> + + <para>To configure Struts project verification select <emphasis> + <property moreinfo="none">Window > Preferences</property> + </emphasis> from the menu bar, select <emphasis> + <property moreinfo="none">JBoss Tools > Web > Verification</property> + </emphasis> from the Preferences dialog box and then expand the + Struts Rules node.</para> + <figure float="0"> + <title>Struts Rules</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/verif_valid/verif_valid_8.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + <para>Suppose you are working in the Source viewer for a Struts + configuration file as shown below:</para> + <figure float="0"> + <title>Struts Configuration File</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/verif_valid/verif_valid_9.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + <para>While typing a class name or entering it from the graphical editor, + you might make a minor typo (like <emphasis role="italic"> + <property moreinfo="none">"sample.GreetingAction1"</property> + </emphasis> instead of <emphasis role="italic"> + <property moreinfo="none">"sample.GreetingAction"</property> + </emphasis>). After saving the file, + <property moreinfo="none">verification</property> checks to make sure everything is + correct and finds the error below:</para> + <figure float="0"> + <title>Error Reporting</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/verif_valid/verif_valid_10.png" scale="75"></imagedata> + </imageobject> + </mediaobject> + </figure> + <para>Notice that the Package Explorer View shows a marked folder and a + marked file where the error is.</para> + <para>You can place the cursor over the line with the error to view a + detailed error message:</para> + <figure float="0"> + <title>Error Message</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/verif_valid/verif_valid_11.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + <para>The verification also checks to make sure you have specified the + correct JSP page for the forward:</para> + <figure float="0"> + <title>JSP Page Verification</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/verif_valid/verif_valid_12.png" scale="75"></imagedata> + </imageobject> + </mediaobject> + </figure> + <para>Once you place the cursor over the line, you can see the error + message:</para> + <figure float="0"> + <title>Error Message</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/verif_valid/verif_valid_13.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + <para>You can always invoke the verification by switching to the Diagram + viewer, right-clicking and selecting <emphasis> + <property moreinfo="none">Verify</property> + </emphasis> from the context menu:</para> + <figure float="0"> + <title>Verify Command</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/verif_valid/verif_valid_14.png"></imagedata> + </imageobject> + </mediaobject> + </figure> +</chapter> + +<chapter id="rel_resources_links" xml:base="file:///home/ochikvina/WORK/for_compare/trunk/struts/docs/struts_tools_ref_guide/en/modules/rel_resources_links.xml"> + <?dbhtml filename="rel_resources_links.html"?> + <chapterinfo> + <keywordset> + <keyword>JBoss Developer Studio</keyword> + <keyword>Eclipse</keyword> + <keyword>Struts Tools</keyword> + <keyword>Java</keyword> + <keyword>JBoss</keyword> + </keywordset> + </chapterinfo> + + <title>Relevant Resources Links</title> + + <para>Find out necessary information on <ulink url="http://struts.apache.org/">Struts + technology</ulink> if you don't know enough.</para> + + <para>In summary, this reference should help you to get familiar with those parts of + <property moreinfo="none">JBoss Tools</property> which are meant for development with Struts + technology. If you've carefully gone through the document, you should know + now how to create/import Struts project or enable Struts capabilities for an + existing web project as well as organize and edit all necessary staff for your + Struts application using a set of views and editors provided by <property moreinfo="none">JBoss + Tools</property>.</para> + + <para>If you'd like to contribute your feedback is always appreciated. You can + leave your questions and suggestions on our <ulink url="http://www.jboss.com/index.html?module=bb&op=viewforum&f=201">Forum</ulink>.</para> +</chapter> + +</book> Modified: branches/jbosstools-3.0.0.CR1/jsf/docs/jsf_tools_ref_guide/en/modules/jsf_project_verification.xml =================================================================== --- branches/jbosstools-3.0.0.CR1/jsf/docs/jsf_tools_ref_guide/en/modules/jsf_project_verification.xml 2008-12-19 19:21:12 UTC (rev 12773) +++ branches/jbosstools-3.0.0.CR1/jsf/docs/jsf_tools_ref_guide/en/modules/jsf_project_verification.xml 2008-12-19 19:26:54 UTC (rev 12774) @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="UTF-8"?> -<chapter id="jsf_project_verification"> +<chapter id="jsf_project_verification" role="updated"> <?dbhtml filename="struts_project_verification.html"?> <chapterinfo> Modified: branches/jbosstools-3.0.0.CR1/jsf/docs/jsf_tools_ref_guide/en/modules/managed_beans.xml =================================================================== --- branches/jbosstools-3.0.0.CR1/jsf/docs/jsf_tools_ref_guide/en/modules/managed_beans.xml 2008-12-19 19:21:12 UTC (rev 12773) +++ branches/jbosstools-3.0.0.CR1/jsf/docs/jsf_tools_ref_guide/en/modules/managed_beans.xml 2008-12-19 19:26:54 UTC (rev 12774) @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="UTF-8"?> -<chapter id="managed_beans"> +<chapter id="managed_beans" role="updated"> <?dbhtml filename="managed_beans.html"?> <chapterinfo> <keywordset> @@ -30,7 +30,7 @@ <para>Thus, in this section we will guides you through all this possibilities.</para> - <section id="CodeGenerationForManagedBeans421"> + <section id="CodeGenerationForManagedBeans421" role="updated"> <title>Code Generation for Managed Beans</title> @@ -158,7 +158,7 @@ The next section will show you how to add an existing Bean into a JSF configuration file.</para> </section> - <section id="AddExistingJavaBeansToAJSFConfigurationFile74332"> + <section id="AddExistingJavaBeansToAJSFConfigurationFile74332" role="updated"> <title>Add Existing Java Beans to a JSF Configuration File</title> <para>If you already have a Java bean you can easily add it to a <property>JSF configuration

15 years, 4 months

1
0
0 / 0

JBoss Tools SVN: r12773 - branches/jbosstools-3.0.0.CR1/as/docs/reference/en.

by jbosstools-commits＠lists.jboss.org

Author: smukhina Date: 2008-12-19 14:21:12 -0500 (Fri, 19 Dec 2008) New Revision: 12773 Added: branches/jbosstools-3.0.0.CR1/as/docs/reference/en/master_output.xml Log: https://jira.jboss.org/jira/browse/JBDS-324 the file to build guide versions with highlighted diff markers Added: branches/jbosstools-3.0.0.CR1/as/docs/reference/en/master_output.xml =================================================================== --- branches/jbosstools-3.0.0.CR1/as/docs/reference/en/master_output.xml (rev 0) +++ branches/jbosstools-3.0.0.CR1/as/docs/reference/en/master_output.xml 2008-12-19 19:21:12 UTC (rev 12773) @@ -0,0 +1,1757 @@ +<?xml version="1.0" encoding="UTF-8"?> +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" +"http://www.docbook.org/xml/4.3/docbookx.dtd" + +[<!ENTITY quick_start SYSTEM "modules/quick_start.xml"> +<!ENTITY runtimes_servers SYSTEM "modules/runtimes_servers.xml"> +<!ENTITY perspective SYSTEM "modules/perspective.xml"> +<!ENTITY webtools SYSTEM "modules/webtools.xml"> +<!ENTITY modules SYSTEM "modules/modules.xml"> +<!ENTITY tptp_support SYSTEM "modules/tptp_support.xml"> + +<!ENTITY seamlink "../../seam/html_single/index.html"> +<!ENTITY aslink "../../as/html_single/index.html"> +<!ENTITY esblink "../../esb_ref_guide/html_single/index.html"> +<!ENTITY gsglink "../../GettingStartedGuide/html_single/index.html"> +<!ENTITY hibernatelink "../../hibernatetools/html_single/index.html"> +<!ENTITY jbpmlink "../../jbpm/html_single/index.html"> +<!ENTITY jsflink "../../jsf/html_single/index.html"> +<!ENTITY jsfreflink "../../jsf_tools_ref_guide/html_single/index.html"> +<!ENTITY jsftutoriallink "../../jsf_tools_tutorial/html_single/index.html"> +<!ENTITY strutsreflink "../../struts_tools_ref_guide/html_single/index.html"> +<!ENTITY strutstutoriallink "../../struts_tools_tutorial/html_single/index.html"> + + +]><book xmlns:diffmk="http://diffmk.sf.net/ns/diff"> + + <bookinfo> + <title>JBoss Server Manager Reference Guide</title> + + <author><firstname>Anatoly</firstname><surname>Fedosik</surname></author> + <author><firstname>Olga</firstname><surname>Chikvina</surname></author> + <author><firstname>Rob</firstname><surname>Stryker</surname><email>rob.stryker(a)jboss.com</email></author> + <author><firstname>Svetlana</firstname><surname>Mukhina</surname><email>smukhina(a)exadel.com</email></author> + + <pubdate>April 2008</pubdate> + <copyright> + <year>2007</year> + <year>2008</year> + <holder>JBoss, a division of Red Hat Inc.</holder> + </copyright> + <releaseinfo><diffmk:wrapper diffmk:change="changed"> + Version: 3.0.0.CR1 + </diffmk:wrapper></releaseinfo> +<abstract> + <title></title> + <para> + <ulink url="http://download.jboss.org/jbosstools/nightly-docs/en/as/pdf/AS_Reference_...">PDF version</ulink> + </para> +</abstract> + + </bookinfo> + + + <toc></toc> + +<chapter id="quick_start" xml:base="file:///home/ochikvina/WORK/for_compare/trunk/as/docs/reference/en/modules/quick_start.xml"> + <title>Quick Start with JBoss Server</title> + + <para>This chapter covers the basics of working with the JBoss server. If you already have + installed JBoss server and runtime you can quickly learn how to configure, start, stop the + server, to know deployment and archiving processes. How to install runtimes and servers read in + the <link linkend="runtimes_servers">Runtimes and Servers in the JBoss AS plugin</link> chapter.</para> + + <para>To start working with JBoss AS, select a <property moreinfo="none">JBoss AS Perspective</property> via + <emphasis><property moreinfo="none">Window > Open Perspective > Other > JBoss AS</property>.</emphasis></para> + + <section id="starting"> + <title>Starting JBoss server</title> + + <para>Starting JBoss server is quite simple. You can control the server behaviour with the help + of a special toolbar in the <property moreinfo="none">JBoss Server View</property> where you could + <property moreinfo="none">start</property> it in a regular or debug mode, <property moreinfo="none">stop</property> it or + <property moreinfo="none">restart</property> it, <property moreinfo="none">publish</property> to the server.</para> + + <figure float="0"> + <title>JBoss Server Toolbar</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/quick_start/quick_start_1.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>To launch the server click the green-with-white-arrow icon on the <property moreinfo="none">JBoss Server + View </property>or right click server name in this view and select <emphasis> + <property moreinfo="none">Start</property> + </emphasis>. If this view is not open, select <emphasis><property moreinfo="none">Window > Show View + > Other > Server > JBoss Server View</property>.</emphasis></para> + + <figure float="0"> + <title>Start JBoss Server</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/quick_start/quick_start_2.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + </section> + + <section id="stopping"> + <title>Stopping JBoss Server</title> + + <para>To stop the server, click the <property moreinfo="none">Stop</property> icon in JBoss Server View or right + click the server name and press <property moreinfo="none">Stop</property>.</para> + + <figure float="0"> + <title>Stop JBoss Server</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/quick_start/quick_start_3.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>When the server is stopped you will see <property moreinfo="none">Stopped</property> next to its name in + the State column.</para> + <para>Learn more about the JBoss Server View <link linkend="JBossServerView">here</link>.</para> + </section> + + <section id="archiving"> + + <title>Project Archiving</title> + + <para>JBoss Tools comes with our own archives tool. The Project Archives plugin consists + primarily of a view to set up each packaging configuration (<emphasis> + <property moreinfo="none">Window > Show View > Other > JBoss Tools > Project archives</property> + </emphasis>).</para> + <para>Right clicking in the <property moreinfo="none">Project Archives View</property> you can create War, EJB + War or EAR archive.</para> + + <figure float="0"> + <title>Archive Creating</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/quick_start/quick_start_7.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>Using the context menu on the item you can initiate a full <property moreinfo="none">build</property> on + archive, <property moreinfo="none">edit</property>, <property moreinfo="none">delete</property> or + <property moreinfo="none">publish</property> it.</para> + + <figure float="0"> + <title>Context Menu on the Item</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/quick_start/quick_start_8.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>Learn more about the <property moreinfo="none">Project Archives View</property> + <link linkend="Project_archivesView">here</link>.</para> + + </section> + <section id="deployment"> + <title>Deploying an Application to a Server</title> + + <para>There are two times to deploy your application:</para> + <itemizedlist> + <listitem> + <para>While creating it</para> + </listitem> + <listitem> + <para>After it already exists</para> + </listitem> + </itemizedlist> + + <para>When you create a new project (Seam, JSF or Struts) with the New Project or Import Project + wizards, the one of wizards steps has a <emphasis> + <property moreinfo="none">Target Runtime</property> + </emphasis> and <emphasis> + <property moreinfo="none">Target Server</property> + </emphasis> sections. You can deploy the application through the appropriate selection in + these sections.</para> + + <figure float="0"> + <title>Runtime and Server Sections in the New Project Wizard</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/quick_start/quick_start_4a.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <figure float="0"> + <title>Runtime and Server Sections in the Import Project Wizard</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/quick_start/quick_start_4b.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>You can deploy an existing application to a server by right-clicking the target defined + server in the <property moreinfo="none">JBoss Servers View</property> and then selecting <property moreinfo="none">Add and + Remove Projects</property> from the context menu.</para> + + <figure float="0"> + <title>Add and Remove Projects From the Context Menu.</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/quick_start/quick_start_5.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>If this application is not assigned to a server, it will be in the left-hand available + projects list. Clicking on the <property moreinfo="none">Add ></property> button will add it to the right-hand + configured projects list and deploy the application to this server.</para> + + <figure float="0"> + <title>Modifying The Projects that are Configured on the Server</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/quick_start/quick_start_6.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>Here, we have just performed the basic steps you should know to quick start with JBoss + server. In fact, there are more functionalities which you can make use of. Further we will talk about them in detail.</para> + </section> + + + <section> + <title>Other relevant resources on the topic</title> + + <para>All JBoss Developer Studio/JBoss Tools documentation you can find <ulink url="http://docs.jboss.org/tools/2.1.0.GA">here</ulink>.</para> + <para>The latest documentation builds are available <ulink url="http://download.jboss.org/jbosstools/nightly-docs/">here</ulink>.</para> + + </section> + +</chapter> + + +<chapter id="runtimes_servers" xml:base="file:///home/ochikvina/WORK/for_compare/trunk/as/docs/reference/en/modules/runtimes_servers.xml" xreflabel="runtimes_servers"> + <?dbhtml filename="runtimes_servers.html"?> + <chapterinfo> + <keywordset> + <keyword>JBoss Developer Studio</keyword> + <keyword>Eclipse</keyword> + <keyword>Deploy</keyword> + <keyword>Deployment</keyword> + <keyword>JBoss</keyword> + </keywordset> + </chapterinfo> + <title>Runtimes and Servers in the JBoss AS plugin</title> + + <para>In this chapter we will discuss how to install runtimes and servers.</para> + + <para>First of all it's necessary to mention that the JBoss AS plugin makes use of WTP. + This includes starting and stopping servers in run or debug mode. It also includes targeting WTP + projects, such as Dynamic Web Projects, to certain server runtimes in order to ensure that the + proper jars from a specific server are added to the project's classpath properly.</para> + <para>In order to get started creating, running, and debugging J2EE applications, we should create + our <property moreinfo="none">runtime</property> and <property moreinfo="none">server</property> instances.</para> + + <section> + <title>Runtimes</title> + <para>In JBoss Tools, the main purpose of Server Runtimes is to point to a server installation + somewhere on disk. In our case, this will be a JBoss installation, and it can then be used for + two primary purposes:</para> + <itemizedlist> + <listitem> + <para>it provides classpath additions to WTP projects that require them.</para> + </listitem> + <listitem> + <para>for <property moreinfo="none">JBoss server</property> at least, it provides information necessary for + the starting and stopping of the server, it tells which jars to run and which + configuration to use.</para> + </listitem> + </itemizedlist> + + <section id="InstNewRuntime"> + <title>Installing a new Runtime</title> + <para>You can install runtimes into eclipse from the <emphasis> + <property moreinfo="none">Window > Preferences... </property> + </emphasis> menu, and then select <emphasis> + <property moreinfo="none">Server > Installed Runtimes</property> + </emphasis> from the categories available.</para> + <figure float="0"> + <title>Installed Runtimes</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/runtimes_servers/runtimes_servers_1.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + <para>From this preference page you can see all declared runtimes and their types as well. + Figure above shows two declared runtimes that include a JBoss 4.2 instance. Here, + it's possible to edit or remove existing runtimes as well as add a new one.</para> + + <para>To create a JBoss runtime click <emphasis> + <property moreinfo="none">Add</property> + </emphasis> button and choose a necessary type of runtime from the appeared dialog. </para> + + <figure float="0"> + <title>Adding a Runtime</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/runtimes_servers/runtimes_servers_2.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>As you can see, <property moreinfo="none">JBoss Tools</property> provide its own adapters such as JBoss + 3.2, 4.0, 4.2 and 5.0 as well. The last one comes with its own new feature, that is a safer + incremental deployment, which prevents partial deployments to be picked up by the server. It + means that scanning for auto-deployment is suspended while files are being copied to the + deployment location and resumed when the copy is completed.</para> + + <note> + <title>Note:</title> + <para>Currently we recommend you to use a fully supported JBoss 4.2 server adapter.</para> + </note> + + <para>You'll also note a Deploy-Only Runtime type. This type provides no classpath + for WTP projects. It is used solely by its server type for the purpose of setting up a + deploy directory for users who don't wish to make use of starting, stopping, or + debugging their projects inside eclipse.</para> + + <figure float="0" id="add_runtime_figure"> + <title>Adding a JBoss 4.2 Runtime</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/runtimes_servers/runtimes_servers_3.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>The following table describes all the available options of the wizard.</para> + <table> + <title>Server Runtime Wizard Parameters</title> + <tgroup cols="2"> + <colspec align="left" colnum="1" colwidth="1*"></colspec> + <colspec colnum="2" colwidth="3*"></colspec> + + <thead> + <row> + <entry align="center"> + <para>Name</para> + </entry> + + <entry align="center"> + <para>Description</para> + </entry> + </row> + </thead> + + <tbody> + <row> + <entry> + <para>Name</para> + </entry> + <entry> + <para>The name of a new Runtime for a chosen server. We suggest that you + don't leave a default value. It's better to give descriptive + names that will help to distinguish one runtime from another.</para> + </entry> + </row> + + <row> + <entry> + <para>Home directory</para> + </entry> + <entry> + <para>The path to a directory where the runtime is installed.</para> + </entry> + </row> + + <row> + <entry> + <para>jRE</para> + </entry> + <entry> + <para>The proper Java Runtime Environment. Because of the open-source nature of + JBoss, a user is likely to want to modify and repackage some of the + configuration-specific jboss jars and create their own configuration. Thus, rather + than forcing you to copy his entire JBoss installation, the structure of the + wizard allows to create only a new configuration instead.</para> + </entry> + </row> + + <row> + <entry> + <para>Configuration</para> + </entry> + <entry> + <para>The list of configurations (all, default, minimal) that is updated as soon as + you browse to a valid runtime installation folder. After the runtime is created + the configuration becomes an unchanging property of that runtime. To compile + against a different configuration's jars, you will need to create a new runtime + from that configuration.</para> + </entry> + </row> + + </tbody> + </tgroup> + </table> + + <para>As a result of having each runtime represent a specific configuration rather than the + server installation as a whole, it is very likely you'll create several different + runtimes to test each of your configurations. It becomes important to ensure your runtimes, + and later your servers, are given descriptive names that help you remember which is which.</para> + + <para>Press <emphasis> + <property moreinfo="none">Finish</property> + </emphasis> to see your new runtime in the list.</para> + </section> + + </section> + + <section> + <title>Servers</title> + <para>WTP servers are eclipse-representations of a backing server installation. They are used to + start or stop servers, deploy to servers, or debug code that will run on the server. They keep + track of the modules (jars, wars, etc) you deploy to the server and also allow you to undeploy + those modules (see <link linkend="run_on_server_wizard">Deploying with Run On Server + Wizard</link> section). </para> + <para>Servers can be started or stopped with different <link linkend="com_line_arg">command-line + arguments</link>. They are often backed by a runtime object representing that server's + location.</para> + + <section> + <title>Creating a New Server</title> + + <para>There are many ways to get to the new server wizard. One way is to use the old standard <emphasis> + <property moreinfo="none">File > New > Other... </property> + </emphasis> and then <emphasis> + <property moreinfo="none">Server</property> + </emphasis>. This should show the wizard like below.</para> + <figure float="0"> + <title>Adding a JBoss Server</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/runtimes_servers/runtimes_servers_4.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + <para>A server object is that keeps track of things like command line arguments when starting + or stopping, and runtimes keep track of the location of the installation. Thus, each server + instance must be backed by an appropriate runtime. </para> + + <para>From the list of already declared runtimes in the combo box below the view it's + possible to select which runtime you want your server to be backed by. If there is no + runtime that matches your needs just press <emphasis> + <property moreinfo="none">Installed Runtimes... </property> + </emphasis> to bring up the familiar preference page like in <link linkend="InstNewRuntime"> + the previous section</link>. Here, it becomes possible to edit already existing runtime or + add a new one with necessary configuration.</para> + + <figure float="0"> + <title>Installed Server Runtime Environments</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/runtimes_servers/runtimes_servers_5.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>If the server you want to create doesn't have any installed runtime yet, the combo box + and button will disappear.</para> + + <figure float="0"> + <title>Installed Server Runtime Environments</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/runtimes_servers/runtimes_servers_6.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>In this case the next page in the wizard which has the same form as in <link linkend="add_runtime_figure">the previous section</link> will ask you to create the + associated runtime.</para> + <para>Either way, after targeting your server to a runtime, the final screen in this wizard is + largely confirmational, giving you a chance to verify that you've selected the + appropriate runtime. It also allows to name the server appropriately. </para> + + <figure float="0"> + <title>Installed Server Runtime Environments</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/runtimes_servers/runtimes_servers_7.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>Press <emphasis> + <property moreinfo="none">Finish</property> + </emphasis> to complete the process of the server creation.</para> + <para>Now that we've created our runtimes and servers, we can dwell on all services + and tools that JBoss Server Manager provides.</para> + </section> + + </section> + +</chapter> + + +<chapter id="perspective" role="updated" xml:base="file:///home/ochikvina/WORK/for_compare/trunk/as/docs/reference/en/modules/perspective.xml" xreflabel="perspective"> + <?dbhtml filename="perspective.html"?> + <chapterinfo> + <keywordset> + <keyword>JBoss Developer Studio</keyword> + <keyword>Eclipse</keyword> + <keyword>Deploy</keyword> + <keyword>Deployment</keyword> + <keyword>JBoss</keyword> + </keywordset> + </chapterinfo> + <title>JBoss AS Perspective</title> + + <para>This chapter tells how to manage installed JBoss Servers via <property moreinfo="none">JBoss AS + Perspective</property>.</para> + + <para>The <property moreinfo="none">JBoss AS Perspective</property> is similar to the <property moreinfo="none"><diffmk:wrapper diffmk:change="changed">Java + Perspective</diffmk:wrapper></property><diffmk:wrapper diffmk:change="changed">, but it contains a few additional views. Two of the additional + views are standard views, specifically the </diffmk:wrapper><property moreinfo="none">Console View</property> and the + <property moreinfo="none">Properties View</property>. The other two views that are added are the + <property moreinfo="none">Project Archives View</property> and the <property moreinfo="none"><diffmk:wrapper diffmk:change="changed">JBoss Server + View</diffmk:wrapper></property>.</para> + + <section id="JBossServerView" role="updated"> + <?dbhtml filename="JBossServerView.html"?> + <title>The JBoss Server View</title> + <para>Let's have a look at the <property moreinfo="none">JBoss Server View</property> and inspect + in detail all parts it consists of. </para> + + <para>The <property moreinfo="none">JBoss Server View</property> is based on the WTP view, Server View. The + top part of the <property moreinfo="none">JBoss Servers View</property> essentially embeds the original + Server View directly into it, making slight changes to the context menu. A second part + was added to provide additional information about the server selected in the top part. </para> + + <figure float="0"> + <title>The JBoss Server View</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/perspective/perspective_1.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + + <para>The view's toolbar provides quick access to starting a server (in debug mode, run + mode, or profile mode), restarting a server, stopping a server, or publishing to a + server.</para> + <figure float="0"> + <title>The JBoss Server View Toolbar</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/perspective/perspective_2.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>In order to debug your applications or EJB's that are deployed to the server, you must + start the server in debug mode. By starting the server in debug mode, eclipse will allow + you to set breakpoints on code in your workspace and step through the code.</para> + + <para><emphasis> + <property moreinfo="none">Start the server in profiling mode</property> + </emphasis> button allows to enable profiling actions for your application. For more + details on how to start using TPTP profiling with <property moreinfo="none">JBoss Tools</property> refer + to <link linkend="tptp_support">TPTP Support</link> chapter.</para> + + <para><emphasis> + <property moreinfo="none">Publish to the server</property> + </emphasis><diffmk:wrapper diffmk:change="changed"> button on the extreme right will republish any modules where it has + determined the workspace is out of sync with the server. It will attempt to do an + incremental publish if it turns out that the module in question is capable of doing + one.</diffmk:wrapper></para> + + <para>Now, let's get to know with both of the <property moreinfo="none"><diffmk:wrapper diffmk:change="changed">JBoss Server + View</diffmk:wrapper></property> parts.</para> + + <section> + <title>Top Part of the JBoss Server View</title> + <para>In the top part of the <property moreinfo="none">JBoss Server View</property> all declared servers + are represented as well as their current states, that is, whether they are started + or stopped. </para> + <figure float="0"> + <title>Server Publish Status</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/perspective/perspective_3.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>The top part also shows the server's publish status. The fallowing table + lists possible statuses.</para> + + <table> + <title>Server Publish Status</title> + <tgroup cols="2"> + <colspec align="left" colnum="1" colwidth="1*"></colspec> + <colspec colnum="2" colwidth="3*"></colspec> + + + <thead> + <row> + <entry align="center">Status</entry> + + <entry align="center">Description</entry> + </row> + </thead> + + <tbody> + <row> + <entry align="center"> + <para>Republish</para> + </entry> + + <entry align="center"> + <para><diffmk:wrapper diffmk:change="changed">The status which allows you to see if changes are + awaiting</diffmk:wrapper></para> + </entry> + </row> + <row> + <entry align="center"> + <para>Publishing...</para> + </entry> + + <entry align="center"> + <para>The status which shows if changes are being updated</para> + </entry> + </row> + <row> + <entry align="center"> + <para>Synchronized</para> + </entry> + + <entry align="center"> + <para><diffmk:wrapper diffmk:change="changed">The status which allows you to see if changes are + in-sync</diffmk:wrapper></para> + </entry> + </row> + </tbody> + </tgroup> + </table> + + <para><diffmk:wrapper diffmk:change="changed">By double-clicking on any server, an editor window will appear allowing you to + edit parts of that server. On the figure you can see that a username/password is + available in the UI when configuring the server. If you get an SecurityException + when trying to launch the server, it is most likely because your server is protected + and hence you need to fill the username/password fields with appropriate + values.</diffmk:wrapper></para> + + <figure float="0"> + <title>Preferences Page for the Chosen Server</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/perspective/perspective_4.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>It should be pointed out that our server adapter by default tries to automatically + detect the ports it needs for integrating with a <property moreinfo="none">JBoss server</property>. + Sometimes it can though be relevant to override this automatic detection if you are + using some custom configuration. For this purposes the <emphasis> + <property moreinfo="none">Server Ports</property> + </emphasis> section in the <property moreinfo="none">Server editor</property><diffmk:wrapper diffmk:change="added"> is provided where the + port settings are configurable. Click the </diffmk:wrapper><emphasis diffmk:change="added"> + <property diffmk:change="added" moreinfo="none"><diffmk:wrapper diffmk:change="added">Configure...</diffmk:wrapper></property> + </emphasis><diffmk:wrapper diffmk:change="added"> link to bring up the wizard for adjusting the settings for the + Ports.</diffmk:wrapper></para> + + <figure diffmk:change="added" float="0"> + <title diffmk:change="added"><diffmk:wrapper diffmk:change="added">Server Ports Preferences</diffmk:wrapper></title> + <mediaobject diffmk:change="added"> + <imageobject diffmk:change="added"> + <imagedata diffmk:change="added" fileref="images/perspective/perspective_5.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para diffmk:change="added"><diffmk:wrapper diffmk:change="added">Press </diffmk:wrapper><emphasis diffmk:change="added"> + <property diffmk:change="added" moreinfo="none"><diffmk:wrapper diffmk:change="added">Edit XPath</diffmk:wrapper></property> + </emphasis><diffmk:wrapper diffmk:change="added"> button for the chosen Port to configure its XPath's values.</diffmk:wrapper></para> + + <figure diffmk:change="added" float="0"> + <title diffmk:change="added"><diffmk:wrapper diffmk:change="added">XPath Pattern for a Server Port</diffmk:wrapper></title> + <mediaobject diffmk:change="added"> + <imageobject diffmk:change="added"> + <imagedata diffmk:change="added" fileref="images/perspective/perspective_6.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para><diffmk:wrapper diffmk:change="changed">The settings related to </diffmk:wrapper><emphasis> + <property moreinfo="none">Publishing</property> + </emphasis>, <emphasis> + <property moreinfo="none">Timeouts</property> + </emphasis> or <emphasis> + <property moreinfo="none">Server Polling</property> + </emphasis><diffmk:wrapper diffmk:change="added"> can be also adjusted in the </diffmk:wrapper><property diffmk:change="added" moreinfo="none"><diffmk:wrapper diffmk:change="added">Server editor</diffmk:wrapper></property><diffmk:wrapper diffmk:change="added">.</diffmk:wrapper></para> + + <para id="com_line_arg"><property moreinfo="none">Server editor</property><diffmk:wrapper diffmk:change="changed"> makes it also possible to + modify the server's launch configuration. It's just after clicking </diffmk:wrapper><emphasis> + <property moreinfo="none">Open launch configuration</property> + </emphasis> link. In the open window there are the tabs for setting command line + arguments and other things that are relevant to launching the server.</para> + + <figure float="0"> + <title>Launch Configuration Properties</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/perspective/perspective_7.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>Look up <ulink url="http://docs.jboss.org/jbossas/guides/installguide/r1/en/html/start-stop.html">here</ulink> to find parameters which can be specified for <property moreinfo="none">JBoss + Server</property>.</para> + + <para>As the JBoss Servers have few properties to modify in this editor, a shortcut to + the launch configuration has been provided in the context menu when right-clicking + on a server.</para> + + <figure float="0"> + <title>Twiddle Server</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/perspective/perspective_8.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>The following table describes all these additional properties.</para> + <table> + <title>Server Properties through the Context Menu</title> + <tgroup cols="2"> + <colspec align="left" colnum="1" colwidth="1*"></colspec> + <colspec colnum="2" colwidth="3*"></colspec> + + <thead> + <row> + <entry align="center"> + <para>Name</para> + </entry> + + <entry align="center"> + <para>Description</para> + </entry> + </row> + </thead> + + <tbody> + <row> + <entry> + <para>New Server</para> + </entry> + <entry> + <para>The option allows to define a new server</para> + </entry> + </row> + + <row> + <entry> + <para>Delete</para> + </entry> + <entry> + <para>Standard option that allows to delete the chosen server</para> + </entry> + </row> + + <row> + <entry> + <para>Start</para> + </entry> + <entry> + <para>The action for stating a server in a run mode</para> + </entry> + </row> + + <row> + <entry> + <para>Debug</para> + </entry> + <entry> + <para>The action for stating a server in a debug mode</para> + </entry> + </row> + + <row> + <entry> + <para>Stop</para> + </entry> + <entry> + <para>The action for stopping a declared server</para> + </entry> + </row> + + <row> + <entry> + <para>Publish</para> + </entry> + <entry> + <para>The action for synching the publish information between the + server and workspace</para> + </entry> + </row> + + <row> + <entry> + <para>Clean</para> + </entry> + <entry> + <para>The option for complete redeploying the resources</para> + </entry> + </row> + + <row> + <entry> + <para>Twiddle Server</para> + </entry> + <entry> + <para>The option provides a dialog for running Twiddle commands + against the Twiddle Server</para> + </entry> + </row> + + <row> + <entry> + <para>Edit Launch Configuration</para> + </entry> + <entry> + <para>The option that provides an editor for editing launch + configuration properties of the proper server</para> + </entry> + </row> + + <row> + <entry> + <para>Add and Remove Projects</para> + </entry> + <entry> + <para>The option allows to publish a new project to the server (if + its type is supported)</para> + </entry> + </row> + </tbody> + </tgroup> + </table> + + <para>Mentioned above Twiddle is a JMX library that comes with JBoss, and you can use it + to access any variables that exposed via the JBoss JMX interfaces.</para> + </section> + + <section> + <title>Bottom Part of the JBoss Server View</title> + + <para>Here, we dwell on the bottom part of the <property moreinfo="none"><diffmk:wrapper diffmk:change="changed">JBoss Server + View</diffmk:wrapper></property>.</para> + <para>First, we should say that the bottom part is meant to provide additional + functionality relevant to the server selected in the top part of the view. If a + standard server element is selected from above, some of the extensions may still + provide the additional information. Others may not. So, let's look at the + currently available extensions to the bottom part of the <property moreinfo="none"><diffmk:wrapper diffmk:change="changed">JBoss Server + View</diffmk:wrapper></property>.</para> + + <figure float="0"> + <title>View Extensions</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/perspective/perspective_9.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>In order to access the view's preferences, you should access <emphasis> + <property moreinfo="none">Window > Preferences > JBoss Tools > JBoss + Servers > View</property> + </emphasis>. This preference page allows you to select which view extensions you + want on or off, the order they appear in the view, as well as any other + extension-specific preferences that may be available.</para> + + <figure float="0"> + <title>View Preferences</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/perspective/perspective_10.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>The first view extension is <emphasis> + <property moreinfo="none">Modules</property> + </emphasis> section. It shows which modules are currently deployed to the server, + and allows you to remove them from the server, or force a full republish upon them. + It only shows which modules have been deployed through Eclipse, not any and all + modules that happen to be in the deploy directory.</para> + + <figure float="0"> + <title>Modules Action</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/perspective/perspective_11.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>The <emphasis> + <property moreinfo="none">Event Log</property> + </emphasis> will show relevant information to your server's startup, + shutdown, and publish processes. This allows you to keep an eye on what's + going on (such as automatic incremental deployment if you have it enabled). The only + action available is to clear the <emphasis> + <property moreinfo="none">Event Log</property> + </emphasis>. However, if the <property moreinfo="none">Properties View</property> is opened, you can + receive further information on each <emphasis> + <property moreinfo="none">Event Log</property> + </emphasis> item (when available).</para> + + <figure float="0"> + <title>Event Log Actions</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/perspective/perspective_12.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <figure float="0"> + <title>Starting the Server</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/perspective/perspective_13.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>The <emphasis> + <property moreinfo="none">XML Configuration</property> + </emphasis> category allows you to quickly browse to descriptor files in your + server's deploy directory and check or change the values. Its use requires the + <property moreinfo="none">Properties view</property>. Basically, <emphasis> + <property moreinfo="none">XML Configuration</property> + </emphasis> includes XML XPaths where a xpath is a path used to access some specific + part of an xml document. </para> + + <figure float="0"> + <title>XML Configuration and Properties View</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/perspective/perspective_14.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <note> + <title>Note:</title> + <para>You are assumed to be familiar with XPath. If not, we highly suggested that + you look through an appropriate manual or tutorial on the topic.</para> + </note> + + <para>The <emphasis> + <property moreinfo="none">XML Configuration</property> + </emphasis> category itself contains only a list of categories. <emphasis> + <property moreinfo="none">Ports</property> + </emphasis> are provided by default and is filled with many of the most commonly + used ports in the <property moreinfo="none">JBoss Server</property>. In the <property moreinfo="none">Properties + view</property> you can see an identifier and nested files underneath in which + that xpath can be found as well as its current value. The details of the xpath are + hidden as all you need to see is only which file you're referring to and + what its current value is.</para> + + <para> By right-clicking on <emphasis> + <property moreinfo="none">XML Configuration</property>, </emphasis> you can create a new + category. Besides, context menu for <emphasis> + <property moreinfo="none">XML Configuration</property> + </emphasis> category makes possible to disable it. You can disable any category in + the bottom part of the <emphasis> + <property moreinfo="none">JBoss Server View</property>.</emphasis> Look for them in the <emphasis> + <property moreinfo="none">Inactive Categories</property> + </emphasis> afterwards to re-enable.</para> + + <figure float="0"> + <title>Adding New Category</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/perspective/perspective_15.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>By right-clicking on <emphasis> + <property moreinfo="none">Ports</property> + </emphasis> or any other category in <emphasis> + <property moreinfo="none">XML Configuration</property> + </emphasis>, you can create a new xpath.</para> + + <figure float="0"> + <title>Adding New XPath</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/perspective/perspective_16.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>After that, the dialog shown below will appear.</para> + + <figure float="0"> + <title>Adding New XPath</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/perspective/perspective_17.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>The goal here is to get an end result where the XPath matches up with a necessary + property. With that in mind, let's look how it works. If the property you + want to reach is the value of the <emphasis>name</emphasis> attribute in the element + <emphasis><mbean></emphasis>, then your <emphasis> + <property moreinfo="none">XPath Patten</property> + </emphasis>should end with <emphasis>mbean</emphasis> and your <emphasis> + <property moreinfo="none">Attribute Name</property> + </emphasis> should be <emphasis>name</emphasis> like on the next figure.</para> + + <programlisting format="linespecific" role="XML"><![CDATA[... +<server> +... + <mbean code="org.jboss.ejb.EJBDeployer" + name="jboss.ejb:service=EJBDeployer" xmbean-dd=""> + +  + <xmbean> + <description> + The EJBDeployer responsible for ejb jar deployment</description> + ... + </xmbean> + </mbean> +</server> +]]></programlisting> + + <figure float="0"> + <title>XPath Preview</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/perspective/perspective_18.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <tip> + <title>Tip:</title> + <para>Notice, when you type the fields autocomplete to help you locate exactly what + xpath you're looking for.</para> + </tip> + + <para>Then, on the other hand, if your desired field is the text of an element + <emphasis><description></emphasis>, your <emphasis> + <property moreinfo="none">XPath Patten</property> + </emphasis> should end with <emphasis>description</emphasis> and <emphasis> + <property moreinfo="none">Attribute Name</property> + </emphasis> field should be left blank. When finished, click <emphasis> + <property moreinfo="none">Preview</property> + </emphasis> to see how many matches you have for that particular XPath.</para> + + <figure float="0"> + <title>XPath Preview</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/perspective/perspective_19.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>As part of the <property moreinfo="none">JBoss Server View</property> there is a <emphasis> + <property moreinfo="none">JMX Console</property> + </emphasis> section which allows you to browse and use the JMX exposed beans on the + server.</para> + <figure float="0"> + <title>JMX Console</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/perspective/perspective_20.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <section> + <title>Relevant Resources Links</title> + <para>Find more about XPath in the <ulink url="http://www.w3.org/TR/xpath20/">XPath + Documentation</ulink>.</para> + </section> + </section> + + </section> + + <section id="Project_archivesView" role="updated"> + <title>Project Archives View</title> + <para>Every application, whether Plain Old Java, J2EE, or some other language altogether, + needs to be packaged in some way. In Java-related projects, many people use ANT. JBoss + Tools comes with our own Archives tool with a bit easier and less-verbose XML and a + handy user interface. The Project Archives plugin consists primarily of a view, that is + <property moreinfo="none">Project Archives View</property><diffmk:wrapper diffmk:change="changed">, to set up each packaging + configuration.</diffmk:wrapper></para> + <para>So far, let's look through all functionality that the <property moreinfo="none">Project + Archives View</property> provides.</para> + + <section id="archives_overview"> + <title>Overview</title> + + <para>The packaging configuration for each project is stored in the project's root + folder, and is in a file named <emphasis> + <property moreinfo="none">.packages</property> + </emphasis>, which has a fairly simple XML structure. Modifying the file by hand is + neither required nor recommended, and using the UI is the official way of modifying + your packaging structure.</para> + + <figure float="0"> + <title>Archives View</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/perspective/perspective_21.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>A project's configuration contains archives. On the image above there is + only one archive, but a project can contain many. Inside the archive folders + (testFolder), filesets, or other internal archives can be located. Internal archives + and filesets may be directly inside of an archive, or in some sub-folder of that + archive.</para> + + <para>In the upper right corner of the view you can see an icon which, when clicked, + will build the selected top-level archive. Additionally, you can select <emphasis> + <property moreinfo="none">Project > Build Packages</property> + </emphasis> when a project is selected in the <property moreinfo="none">Packages View</property> to + build all declared packages in that project's <emphasis> + <property moreinfo="none">.packages</property> + </emphasis> file. This will execute a full build on all declared archives.</para> + </section> + + <section id="Creating_Archive"> + <title>Creating an Archive</title> + <para>When creating a new archive, you have some different options at your disposal. If + the project has no <emphasis> + <property moreinfo="none">.packages</property> + </emphasis> file, your options will be presented to you all at once to choose from. + Otherwise you will right-click inside the view and select <emphasis> + <property moreinfo="none">New Archive</property> + </emphasis> to see your archive type options.</para> + <figure float="0"> + <title>Create an Archive</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/perspective/perspective_22.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <note> + <title>Note:</title> + <para><diffmk:wrapper diffmk:change="changed">If you see only JAR from the list of available archive types, you should + verify whether AS Tools plugins/features are in place. EAR, EJB JAR and WAR + options are contributed by the AS Tools independently from webtools and the + virtual project model. Thus, without them only JAR will show up.</diffmk:wrapper></para> + </note> + + <para><property moreinfo="none">JAR</property> is the standard archive type, and does very little + configuration, leaving most of the work up to you. You can customize the name, add + folders, filesets, and inner jars to it.</para> + <para>The other types, for the most part, simply start off with a default setting, + usually the jar with some specific children based on an expected structure of the + project. For example, if the project is a Dynamic Web Project, and you create a + <property moreinfo="none">WAR</property> archive, the archive will be created with a few + filesets relevant to the known structure of the project.</para> + + <para>Here is the first page of all New archive wizards. It is the same for any archive + type and the only page in the <property moreinfo="none">New Jar Wizard</property>.</para> + <figure float="0"> + <title>New JAR Wizard</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/perspective/perspective_23.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>The page is pretty simple. All it asks for is the name of your new archive, a + destination, which we'll get to in a moment, and whether the archive is exploded or + packaged up.</para> + <para>The destination of an archive can be anywhere on the filesystem, anywhere in the + workspace, inside some other archive, or inside a folder declared inside an archive. + You can browse to workspace or filesystem destinations by clicking on their + respective buttons. To select a destination inside some other archive, you'll need + to press the <emphasis> + <property moreinfo="none">Workspace...</property> + </emphasis> button. At the bottom of the list, you'll see archives that + have been declared in the workspace.</para> + <section id="CreatingaFolder"> + <title>Creating a Folder</title> + <para>Creating a folder is much easier. You simply right-click on an archive or + folder you want your new folder to be a child under. The only piece of required + information is naming the file.</para> + </section> + <section id="CreatingaFileSet"> + <title>Creating a FileSet</title> + <para>To create a new fileset, you click on an available target location such as an + archive, a nested archive, or a folder within an archive, and select <emphasis> + <property moreinfo="none">New Fileset</property> + </emphasis>.</para> + <para>The <property moreinfo="none">New Fileset Wizard</property> requires a destination (where the + files will go), and a root directory (or where the files are coming from). The + source can be anywhere in the workspace or from the filesystem at large.</para> + + <figure float="0"> + <title>Adding a New FileSet</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/perspective/perspective_24.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>Below that, the fileset requires only an includes pattern and an excludes + pattern. As you type in either of these fields, the preview viewer should update + itself with which files are matched.</para> + </section> + </section> + <section id="View_Actions"> + <title>Archive Actions</title> + <figure float="0"> + <title>Context Menu on the Item</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/perspective/perspective_25.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + <para>The context menu on the items in the view is extendable, but there are several + that come standard.</para> + + <table> + <title>Context Menu on the Item</title> + <tgroup cols="2"> + <colspec align="left" colnum="1" colwidth="1*"></colspec> + <colspec colnum="2" colwidth="3*"></colspec> + + + <thead> + <row> + <entry align="center"> + <para>Name</para> + </entry> + + <entry align="center"> + <para>Description</para> + </entry> + </row> + </thead> + + <tbody> + + <row> + <entry> + <para>Build Archive (Full)</para> + </entry> + + <entry> + <para>The action enabled only on top-level archives, which initiates + a full build on that archive</para> + </entry> + </row> + + <row> + <entry> + <para>Edit Archive</para> + </entry> + + <entry> + <para>Standard action that brings up the wizard associated with that + particular node type and allows the details to be changed</para> + </entry> + </row> + + <row> + <entry> + <para>Delete Archive</para> + </entry> + + <entry> + <para>Deleting node is standard action with deletion not needing an + explanation</para> + </entry> + </row> + + <row> + <entry> + <para>Publish To Server</para> + </entry> + + <entry> + <para><diffmk:wrapper diffmk:change="changed">The action means the ability to publish to a declared + server</diffmk:wrapper></para> + </entry> + </row> + + </tbody> + </tgroup> + </table> + </section> + + <section id="PublishToServer"> + <title>Publishing to Server</title> + <para>Finally, you'll need to publish your application to a server. Here, we + show you how to do it with the help of <emphasis> + <property moreinfo="none">Archives View</property> + </emphasis>.</para> + + <figure float="0"> + <title>Context Menu on the Item</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/perspective/perspective_26.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + <para>The dialog above appears after selecting <emphasis> + <property moreinfo="none">Publish To Server</property> + </emphasis>. To simply publish once, you just select the server(s) that you want, + and finish. If you want the <emphasis> + <property moreinfo="none">Publish to Server</property> + </emphasis> action on that particular Archive to publish always to that set of + servers, then check the appropriate checkbox. And finally, to enable automatic + publishing upon build events, check the last checkbox.</para> + <para>The automatic publishing feature is nice if, for example, your package's + destination (where it is built) is a temporary folder and you want the archive + published to several servers. If you only really want your archive published to one + server, it might be easier to have the archive's destination folder be the deploy + folder of the server.</para> + </section> + <section> + <title>Relevant Resources Links</title> + <para>Refer to <ulink url="http://ant.apache.org/manual/index.html">Ant manual</ulink> + to find more on how to build your applications with help of Ant.</para> + + <para>At this point, you are guessed to be familiar with <property moreinfo="none"><diffmk:wrapper diffmk:change="changed">JBoss AS + Perspective</diffmk:wrapper></property> and your next step now is to explore how to work with + different kinds of projects.</para> + </section> + + </section> + + +</chapter> + + +<chapter id="webtools" xml:base="file:///home/ochikvina/WORK/for_compare/trunk/as/docs/reference/en/modules/webtools.xml"> + <title>Projects</title> + <para>The most popular of the projects we deal with are the J2EE ones, such as Dynamic Web + Project, EJB Project, or EAR project. Web projects of <property moreinfo="none">JBoss Tools</property> are + Struts, JSF and Seam projects. All of them are called faceted projects. Thus, in this + chapter we are going to tell you about facets the main benefit of which to provide proper + structuring and packaging for any type of project.</para> + + <section> + <title>Faceted Projects Overview</title> + <para>The idea behind faceted projects is that each project can accept units of + functionality, or facets, which can be added or removed by the user. Most often, these + facets either add to the project's classpath, enable a builder, or watch the project in + some other fashion. Generally, every project concerned has at least one facet when + it's created. As an example, a Web project has a WebDoclet facet, or an EJB + Project has an EJB Module facet as prerequisites.</para> + + <para> WTP projects have undergone some criticism as being + <emphasis>over-engineered</emphasis> or too restrictive in their design. WTP projects + are set up in a tree-relationship to each other, where one project can be a child of + another. For example, an EAR project may have a Web Project child, an EJB project child, + or other types.</para> + + <para> However, the benefit of this is that the structure of your projects is then known, + and packaging it up *should* be trivial. Apparently, if your project is non-standard, or + you feel too confined by such rigid structural requirements, you can still choose to + package your project using the <link linkend="Project_archivesView">Archives + plugin</link>.</para> + </section> + + + <section> + <title>Adding Facets to a Project</title> + + <para>In this section we're going to consider the facets added by <property moreinfo="none">JBoss + Tools</property> and show how you can configure them in a project: add new ones or + modify already existing configuration of the facets.</para> + + <para>One way to configure the facets is doing it while organizing a new project. To + demonstrate this let's create a new <property moreinfo="none">Dynamic Web Project</property> by + selecting <emphasis> + <property moreinfo="none">File > New > Other...</property> + </emphasis> and then <emphasis> + <property moreinfo="none">Web > Dynamic Web Project</property>. </emphasis></para> + <figure float="0"> + <title>New Dynamic Web Project</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/webtools/webtools_1.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + <para>Click <emphasis> + <property moreinfo="none">Next</property> + </emphasis> and you will see Dynamic Web Project page like on the figure below.</para> + + <para> The first page of most WTP projects allows you to target a specific runtime, + representing a server's library location. It will also provide you the ability to add + this project to an EAR project, and select a pre-selected default set of facets, called + a configuration, rather than manually select each facet you might want.</para> + <para> Selecting the runtime, again, allows the project to install the proper classpaths to + the project so it knows what code to compile against.</para> + + <figure float="0" id="dyn_web_project"> + <title>New Dynamic Web Project</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/webtools/webtools_2.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + <para>Click on the <emphasis> + <property moreinfo="none">Modify</property> + </emphasis> button next to <property moreinfo="none">Configuration</property> section in order to open + the wizard which allows you to modify a chosen configuration. The wizard looks as + follows.</para> + + <figure float="0" id="project_facets"> + <title>Project Facets Wizard</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/webtools/webtools_3.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>Here part of the listed facets are those which are provided by WTP. Some of them are + added by <property moreinfo="none">JBoss Tools</property>. They are:</para> + <itemizedlist> + <listitem> + <para>BIRT Charting Runtime Component</para> + </listitem> + <listitem> + <para>BIRT Reporting Runtime Component</para> + </listitem> + <listitem> + <para>JBoss ESB</para> + </listitem> + <listitem> + <para>JBoss Portlets</para> + </listitem> + <listitem> + <para>JBoss Web Services</para> + </listitem> + <listitem> + <para>Seam</para> + </listitem> + </itemizedlist> + + <para>On this wizard page you can enable or disable any facet as well as change it version. + What you should note here is that some facets or facets versions may conflict with each + other. In case of incompatibility you'll be prompted about this in the combo + box underneath.</para> + <figure float="0"> + <title>Facet Constraints</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/webtools/webtools_4.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + <para>When switching on the <emphasis> + <property moreinfo="none">Runtimes</property> + </emphasis> tab on the right you'll see the currant Server Runtime.</para> + <figure float="0"> + <title>Runtimes on the Project Facets Wizard</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/webtools/webtools_5.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + <para>On this tab you can also create a new Server Runtime and make it primary by pressing <emphasis> + <property moreinfo="none">Make Primary</property> + </emphasis> button after enabling it.</para> + + <para>Clicking on <emphasis> + <property moreinfo="none">OK</property> + </emphasis> will save the chosen configuration of the facets and return you to the <link linkend="dyn_web_project">Dynamic Web Project wizard</link>. Further pages in the + wizard are specific to either the project type or the facets selected.</para> + + + <para>If you need to configure the facets for the existing project, you should bring up the + context menu for selected project and click <emphasis> + <property moreinfo="none">Properties</property> + </emphasis> and then <emphasis> + <property moreinfo="none">Project Facets</property>. </emphasis> This will bring up the familiar + <link linkend="project_facets">Project Facets wizard</link>, where you can create + your own custom facets configuration.</para> + + <para></para> + + </section> + <section id="rel_resources_links"> + <title>Relevant Resources Links</title> + + <para>More on the WTP facets you can read in the <ulink url="http://help.eclipse.org/ganymede/index.jsp?topic=/org.eclipse.jst.j2ee.do...">eclipse help</ulink>.</para> + </section> +</chapter> + + +<chapter id="modules" xml:base="file:///home/ochikvina/WORK/for_compare/trunk/as/docs/reference/en/modules/modules.xml"> + <title>Deploying Modules</title> + + <para>In this chapter it will be described how to deploy modules onto the server.</para> + <para> First of all it is necessary to say that deploying to a server is mostly painless. There + are several ways to do it provided by WTP, and some additional methods provided by JBoss + Tools. These methods are described further in this chapter.</para> + + <section> + <title>Deploying on the Package Explorer</title> + + <para>On the package explorer it is possible to publish either a project to a server or just + a signal file. Let's look at how to do this.</para> + <section id="run_on_server_wizard"> + <title>Deploying with Run On Server Wizard</title> + <para> The first WTP method is to right-click on a project, such as a Dynamic Web + project, EJB project, or EAR project and then select <emphasis> + <property moreinfo="none">Run As > Run on Server</property> + </emphasis>. The resulting dialog allows you to select which supporting server the + project can be published to.</para> + <figure float="0"> + <title>Define a New Server</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/modules/modules_1.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + <para>Click <emphasis> + <property moreinfo="none">Next</property> + </emphasis> button to see add or remove projects page where you can choose projects + to configure them on server.</para> + <figure float="0" id="add_rem_proj"> + <title>Add or Remove Projects</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/modules/modules_2.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + <para>This page of the wizard also allows to undeploy modules from the server. For that + choose proper module(s) from the right and click <emphasis> + <property moreinfo="none"> < Remove</property> + </emphasis>. The modules will be completely undeployed after restarting your server + or republishing.</para> + <para>Generally, for the JBoss AS Server Adapters, publishing using this method will + force a default, best-guess, packaging configuration for your project. This + best-guess does not publish incrementally, but instead repackages your entire + project into a <emphasis> + <property moreinfo="none">.war</property> + </emphasis>, <emphasis> + <property moreinfo="none">.jar</property> + </emphasis>, or <emphasis> + <property moreinfo="none">.ear</property> + </emphasis> as appropriate, and then copies that file into the proper deploy + directory. For quicker smarter deployment, you will need to create archives using + the <link linkend="Project_archivesView">Project Archives view</link> and customize + packaging yourself.</para> + </section> + + <section id="single_file_deployment"> + <?dbhtml filename="DeployToServer.html"?> + <title>Deploying single files</title> + + <para>Sometimes it becomes necessary to deploy one or more files to a server. For + that in order not to do a full republish in the context menu of files a <emphasis><property moreinfo="none">Deploy To Server</property></emphasis> + option is provided that allows a single file deployment. To deploy these non-WTP files/projects + right click on the file (<emphasis> + <property moreinfo="none">-ds.xml</property></emphasis>, <emphasis> + <property moreinfo="none">.ear</property></emphasis>, <emphasis> + <property moreinfo="none">.jar</property></emphasis> etc.) and select <emphasis> + <property moreinfo="none">Deploy To Server</property> + </emphasis> and it will be automatically deployed.</para> + <figure float="0"> + <title>Deploy to Sever</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/modules/modules_6.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + <para>The deployed files are listed side-by-side with other modules that are deployed to + the server.</para> + + <figure float="0"> + <title>Deployed files on the Server</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/modules/modules_7.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + </section> + + </section> + <section> + <title>Deploying with JBoss Server View</title> + <para>As it has been already mentioned <property moreinfo="none">JBoss Server View</property> contains two + parts: the top part that displays all defined servers and the bottom part which provides + categories with additional information. Thus, in this section we suggest two more ways + to deploy resources onto the server.</para> + <section> + <title>Top part of JBoss Server View</title> + <para>In the top part of the <property moreinfo="none">JBoss Servers View</property> like in the Servers + View you should right click on a server and select the <emphasis> + <property moreinfo="none">Add and Remove Projects</property> + </emphasis> menu item.</para> + <figure float="0"> + <title>Add and Remove Projects</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/modules/modules_3.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>This will bring up a <link linkend="add_rem_proj">familiar dialog</link> allowing + you to either publish projects or modules to a server, or remove them from the + server. If the selected module is a project like a Dynamic Web project, EJB project, + or EAR project, it will be published as through <emphasis> + <property moreinfo="none">Run on Server</property> + </emphasis> wizard, with a best-guess full package. If, however, the selected + element is an archive from the <link linkend="Project_archivesView">Project Archives + view</link>, it will be published according to the rules of that module + type.</para> + </section> + + <section> + <title>Bottom part of JBoss Server View</title> + <para>In the bottom part of <emphasis> + <property moreinfo="none">JBoss Server View</property> + </emphasis> there is a category called <emphasis> + <property moreinfo="none">Modules</property> + </emphasis> which should display all currently-published modules on the server. + Right-clicking on the desired module and selecting <emphasis> + <property moreinfo="none">Full Publish</property> + </emphasis> will force a full rebuild of the entire module.</para> + <figure float="0"> + <title>Full Publish</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/modules/modules_4.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>Here, <emphasis> + <property moreinfo="none">Incremental Publish</property> + </emphasis> is meant to enable publishing of only those parts where changes have + been made.</para> + </section> + </section> + <section> + <title>Deploying with Project Archives View</title> + <para>In the <property moreinfo="none">Project Archives View</property> you can right-click on any declared + archive and select the <emphasis> + <property moreinfo="none">Publish To Server</property> + </emphasis> element. For more on this subject, see <link linkend="PublishToServer">Publishing to Server</link> in the Project Archives View section.</para> + <figure float="0"> + <title>Publish to Server</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/modules/modules_5.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + <para> The only way to ensure an <emphasis> + <property moreinfo="none">Incremental Build</property> + </emphasis>, such as changes to one <emphasis> + <property moreinfo="none">.jsp</property>, </emphasis> + <emphasis> + <property moreinfo="none">.html</property>, </emphasis> or <emphasis> + <property moreinfo="none">.class</property> + </emphasis> file, is to enable the builder for that project. This is done by either + changing the global preferences for the <property moreinfo="none">Archives View</property>, or by + enabling project-specific preferences and ensuring the builder is on.</para> + <para>The last chapter covers a variety of methods on how you can deploy needed modules onto a + server.</para> + </section> +</chapter> + + +<chapter id="tptp_support" xml:base="file:///home/ochikvina/WORK/for_compare/trunk/as/docs/reference/en/modules/tptp_support.xml"> + <title>TPTP Support</title> + <para>This chapter provides an overview on how to enable TPTP Profiling for <property moreinfo="none">JBoss + AS</property> adapters in <property moreinfo="none">JBoss Tools</property>.</para> + + <section> + <title>TPTP Profiling</title> + + <para>To get TPTP profiling work on <property moreinfo="none">JBoss Application Server</property> you should + first download <ulink url="http://www.eclipse.org/downloads/download.php?file=/tptp/4.5.0/TPTP-4.5.0...">TPTP 4.5.0 Runtime</ulink> and install it, i. e. just add the content of <emphasis> + <property moreinfo="none">plugins/features</property> + </emphasis> folders from downloaded directory to the same folders in your eclipse + installation directory.</para> + + <para>And now all profile actions should work for you. To start <property moreinfo="none">JBoss + AS</property> in profiling mode use <emphasis> + <property moreinfo="none">Start the server in profiling mode</property> + </emphasis> button or <emphasis> + <property moreinfo="none">Profile As > Profile on Server</property> + </emphasis> option in the context menu of the project.</para> + + <figure float="0"> + <title>Start the Server in Profiling mode</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/tptp_support/tptp_support_1.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + + <para>To enable TPTP features in your workbench use <property moreinfo="none">Profiling and Logging + Perspective</property> that you can find in the list of proposed perspectives: <emphasis> + <property moreinfo="none">Window > Open Perspective > Other…</property> + </emphasis> + </para> + + <figure float="0"> + <title>Profiling and Logging Perspective</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/tptp_support/tptp_support_2.png"></imagedata> + </imageobject> + </mediaobject> + </figure> + </section> + + <section> + <title>Relevant Resources Links</title> + <para>All additional information on TPTP(Test and Performance Tools Platform) you can find + in <ulink url="http://www.eclipse.org/tptp/home/downloads/4.5.0/documents/quicktour/quic...">eclipse documentation</ulink>.</para> + <para>In summary, this reference should help you to start with <ulink url="http://www.jboss.org/jbossas">JBoss AS</ulink> and get to know with functionality + for work with it.</para> + </section> +</chapter> + + +</book>

15 years, 4 months

1
0
0 / 0

JBoss Tools SVN: r12772 - in branches/jbosstools-3.0.0.CR1/as/docs/reference/en: modules and 1 other directory.

by jbosstools-commits＠lists.jboss.org

Author: smukhina Date: 2008-12-19 14:19:57 -0500 (Fri, 19 Dec 2008) New Revision: 12772 Modified: branches/jbosstools-3.0.0.CR1/as/docs/reference/en/master.xml branches/jbosstools-3.0.0.CR1/as/docs/reference/en/modules/modules.xml branches/jbosstools-3.0.0.CR1/as/docs/reference/en/modules/perspective.xml branches/jbosstools-3.0.0.CR1/as/docs/reference/en/modules/quick_start.xml branches/jbosstools-3.0.0.CR1/as/docs/reference/en/modules/runtimes_servers.xml branches/jbosstools-3.0.0.CR1/as/docs/reference/en/modules/tptp_support.xml branches/jbosstools-3.0.0.CR1/as/docs/reference/en/modules/webtools.xml Log: https://jira.jboss.org/jira/browse/JBDS-324 latest docs that are done for release 3.0.0.CR1 from trunk are added to branch Modified: branches/jbosstools-3.0.0.CR1/as/docs/reference/en/master.xml =================================================================== --- branches/jbosstools-3.0.0.CR1/as/docs/reference/en/master.xml 2008-12-19 19:15:32 UTC (rev 12771) +++ branches/jbosstools-3.0.0.CR1/as/docs/reference/en/master.xml 2008-12-19 19:19:57 UTC (rev 12772) @@ -41,7 +41,7 @@ <holder>JBoss, a division of Red Hat Inc.</holder> </copyright> <releaseinfo> - Version: 3.0.0.beta1 + Version: 3.0.0.CR1 </releaseinfo> <abstract> <title/> Modified: branches/jbosstools-3.0.0.CR1/as/docs/reference/en/modules/modules.xml =================================================================== --- branches/jbosstools-3.0.0.CR1/as/docs/reference/en/modules/modules.xml 2008-12-19 19:15:32 UTC (rev 12771) +++ branches/jbosstools-3.0.0.CR1/as/docs/reference/en/modules/modules.xml 2008-12-19 19:19:57 UTC (rev 12772) @@ -7,7 +7,7 @@ are several ways to do it provided by WTP, and some additional methods provided by JBoss Tools. These methods are described further in this chapter.</para> - <section revisionflag="changed"> + <section> <title>Deploying on the Package Explorer</title> <para>On the package explorer it is possible to publish either a project to a server or just Modified: branches/jbosstools-3.0.0.CR1/as/docs/reference/en/modules/perspective.xml =================================================================== --- branches/jbosstools-3.0.0.CR1/as/docs/reference/en/modules/perspective.xml 2008-12-19 19:15:32 UTC (rev 12771) +++ branches/jbosstools-3.0.0.CR1/as/docs/reference/en/modules/perspective.xml 2008-12-19 19:19:57 UTC (rev 12772) @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="UTF-8"?> -<chapter id="perspective" xreflabel="perspective"> +<chapter id="perspective" xreflabel="perspective" role="updated"> <?dbhtml filename="perspective.html"?> <chapterinfo> <keywordset> @@ -22,7 +22,7 @@ <property>Project Archives View</property> and the <property>JBoss Server View</property>.</para> - <section id="JBossServerView"> + <section id="JBossServerView" role="updated"> <?dbhtml filename="JBossServerView.html"?> <title>The JBoss Server View</title> <para>Let's have a look at the <property>JBoss Server View</property> and inspect @@ -75,7 +75,7 @@ <para>Now, let's get to know with both of the <property>JBoss Server View</property> parts.</para> - <section role="updated"> + <section> <title>Top Part of the JBoss Server View</title> <para>In the top part of the <property>JBoss Server View</property> all declared servers are represented as well as their current states, that is, whether they are started @@ -595,7 +595,7 @@ </section> - <section id="Project_archivesView"> + <section id="Project_archivesView" role="updated"> <title>Project Archives View</title> <para>Every application, whether Plain Old Java, J2EE, or some other language altogether, needs to be packaged in some way. In Java-related projects, many people use ANT. JBoss Modified: branches/jbosstools-3.0.0.CR1/as/docs/reference/en/modules/quick_start.xml =================================================================== --- branches/jbosstools-3.0.0.CR1/as/docs/reference/en/modules/quick_start.xml 2008-12-19 19:15:32 UTC (rev 12771) +++ branches/jbosstools-3.0.0.CR1/as/docs/reference/en/modules/quick_start.xml 2008-12-19 19:19:57 UTC (rev 12772) @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="ISO-8859-1"?> -<chapter id="quick_start" revisionflag="added"> +<chapter id="quick_start"> <title>Quick Start with JBoss Server</title> <para>This chapter covers the basics of working with the JBoss server. If you already have Modified: branches/jbosstools-3.0.0.CR1/as/docs/reference/en/modules/runtimes_servers.xml =================================================================== --- branches/jbosstools-3.0.0.CR1/as/docs/reference/en/modules/runtimes_servers.xml 2008-12-19 19:15:32 UTC (rev 12771) +++ branches/jbosstools-3.0.0.CR1/as/docs/reference/en/modules/runtimes_servers.xml 2008-12-19 19:19:57 UTC (rev 12772) @@ -187,7 +187,7 @@ arguments</link>. They are often backed by a runtime object representing that server's location.</para> - <section revisionflag="changed"> + <section> <title>Creating a New Server</title> <para>There are many ways to get to the new server wizard. One way is to use the old standard <emphasis> Modified: branches/jbosstools-3.0.0.CR1/as/docs/reference/en/modules/tptp_support.xml =================================================================== --- branches/jbosstools-3.0.0.CR1/as/docs/reference/en/modules/tptp_support.xml 2008-12-19 19:15:32 UTC (rev 12771) +++ branches/jbosstools-3.0.0.CR1/as/docs/reference/en/modules/tptp_support.xml 2008-12-19 19:19:57 UTC (rev 12772) @@ -1,5 +1,5 @@ <?xml version="1.0" encoding="UTF-8"?> -<chapter id="tptp_support" role="new"> +<chapter id="tptp_support"> <title>TPTP Support</title> <para>This chapter provides an overview on how to enable TPTP Profiling for <property>JBoss AS</property> adapters in <property>JBoss Tools</property>.</para> Modified: branches/jbosstools-3.0.0.CR1/as/docs/reference/en/modules/webtools.xml =================================================================== --- branches/jbosstools-3.0.0.CR1/as/docs/reference/en/modules/webtools.xml 2008-12-19 19:15:32 UTC (rev 12771) +++ branches/jbosstools-3.0.0.CR1/as/docs/reference/en/modules/webtools.xml 2008-12-19 19:19:57 UTC (rev 12772) @@ -30,7 +30,7 @@ </section> - <section revisionflag="changed"> + <section> <title>Adding Facets to a Project</title> <para>In this section we're going to consider the facets added by <property>JBoss

15 years, 4 months

1
0
0 / 0

JBoss Tools SVN: r12771 - in branches/jbosstools-3.0.0.CR1/documentation/jboss-tools-docs: index/en and 1 other directory.

by jbosstools-commits＠lists.jboss.org

Author: smukhina Date: 2008-12-19 14:15:32 -0500 (Fri, 19 Dec 2008) New Revision: 12771 Modified: branches/jbosstools-3.0.0.CR1/documentation/jboss-tools-docs/all-guides.xml branches/jbosstools-3.0.0.CR1/documentation/jboss-tools-docs/index/en/master.xml Log: https://jira.jboss.org/jira/browse/JBDS-324 docs from trunk are added to branch Modified: branches/jbosstools-3.0.0.CR1/documentation/jboss-tools-docs/all-guides.xml =================================================================== --- branches/jbosstools-3.0.0.CR1/documentation/jboss-tools-docs/all-guides.xml 2008-12-19 19:15:17 UTC (rev 12770) +++ branches/jbosstools-3.0.0.CR1/documentation/jboss-tools-docs/all-guides.xml 2008-12-19 19:15:32 UTC (rev 12771) @@ -137,6 +137,19 @@ <fileMode>0644</fileMode> <directoryMode>0755</directoryMode> </fileSet> + <fileSet> + <directory>../../jbpm/docs/converter_ref/target/docbook/publish/en-US</directory> + <outputDirectory>/jboss_bpmn_convert_ref_guide</outputDirectory> + <filtered>false</filtered> + <lineEnding>keep</lineEnding> + <includes> + <include>**/*.*</include> + </includes> + <useStrictFiltering>false</useStrictFiltering> + <useDefaultExcludes>true</useDefaultExcludes> + <fileMode>0644</fileMode> + <directoryMode>0755</directoryMode> + </fileSet> <fileSet> <directory>../../jsf/docs/userguide/target/docbook/publish/en-US</directory> <outputDirectory>/jsf</outputDirectory> @@ -273,6 +286,20 @@ <fileMode>0644</fileMode> <directoryMode>0755</directoryMode> </fileSet> + + <fileSet> + <directory>../../smooks/docs/reference/target/docbook/publish/en-US</directory> + <outputDirectory>/jboss_smooks_plugin_ref_guide</outputDirectory> + <filtered>false</filtered> + <lineEnding>keep</lineEnding> + <includes> + <include>**/*.*</include> + </includes> + <useStrictFiltering>false</useStrictFiltering> + <useDefaultExcludes>true</useDefaultExcludes> + <fileMode>0644</fileMode> + <directoryMode>0755</directoryMode> + </fileSet> </fileSets> </assembly> \ No newline at end of file Modified: branches/jbosstools-3.0.0.CR1/documentation/jboss-tools-docs/index/en/master.xml =================================================================== --- branches/jbosstools-3.0.0.CR1/documentation/jboss-tools-docs/index/en/master.xml 2008-12-19 19:15:17 UTC (rev 12770) +++ branches/jbosstools-3.0.0.CR1/documentation/jboss-tools-docs/index/en/master.xml 2008-12-19 19:15:32 UTC (rev 12771) @@ -143,6 +143,33 @@ >(pdf)</ulink> </primaryie> </indexentry> + + <indexentry> + <primaryie>Smooks Reference Guide <ulink + url="en/jboss_smooks_plugin_ref_guide/html/index.html">(html)</ulink> + <ulink url="en/jboss_smooks_plugin_ref_guide/html_single/index.html">(html single)</ulink> + <ulink url="en/jboss_smooks_plugin_ref_guide/pdf/Smooks_Reference_Guide.pdf" + >(pdf)</ulink> + </primaryie> + </indexentry> + <indexentry> + <primaryie>BPMN Convert Reference Guide <ulink + url="en/jboss_bpmn_convert_ref_guide/html/index.html">(html)</ulink> + <ulink url="en/jboss_bpmn_convert_ref_guide/html_single/index.html">(html single)</ulink> + <ulink url="en/jboss_bpmn_convert_ref_guide/pdf/Converter_Reference_Guide.pdf" + >(pdf)</ulink> + </primaryie> + </indexentry> + + <indexentry> + <primaryie>jBPM Reference Guide <ulink + url="en/jboss_jbpm_ref_guide/html/index.html">(html)</ulink> + <ulink url="en/jboss_jbpm_ref_guide/html_single/index.html">(html single)</ulink> + <ulink url="en/jboss_jbpm_ref_guide/pdf/JBPM_Reference_Guide.pdf" + >(pdf)</ulink> + </primaryie> + </indexentry> + </index> </book>

15 years, 4 months

1
0
0 / 0

2024

2023

2022

2021

2020

2019

2018

2017

2016

2015

2014

2013

2012

2011

2010

2009

2008

2007

jbosstools-commits December 2008