Author: smukhina Date: 2010-03-18 13:19:35 -0400 (Thu, 18 Mar 2010) New Revision: 20907 Modified: trunk/esb/docs/esb_ref_guide/en-US/esb_editor.xml trunk/esb/docs/esb_ref_guide/en-US/esb_support.xml Log: https://jira.jboss.org/jira/browse/JBDS-1164 Documentation issues in ESB Tools Reference Guide - fixed Modified: trunk/esb/docs/esb_ref_guide/en-US/esb_editor.xml =================================================================== --- trunk/esb/docs/esb_ref_guide/en-US/esb_editor.xml 2010-03-18 15:59:15 UTC (rev 20906) +++ trunk/esb/docs/esb_ref_guide/en-US/esb_editor.xml 2010-03-18 17:19:35 UTC (rev 20907) @@ -12,7 +12,7 @@ <title>ESB Editor</title> <para> ESB editor has lots of useful features, they are described in details in this chapter. In - addition you&apos;ll get to know with how <property>ESB Editor</property> uses combined + addition you&apos;ll get to know how <property>ESB Editor</property> uses combined visual and source editing of esb files.</para> <section id="esb_file" role="updated"> @@ -195,7 +195,7 @@ </mediaobject> </figure> - <para>As you can see on the bath figures above, the context menu will also prompt you to + <para>As you can see on the both figures above, the context menu will also prompt you to insert one of the Actions that are supplied out-of-the-box with <property>JBoss ESB</property>. After choosing one an appeared <property>New Pre-Packed Action </property>wizard will ask you to fill out a name field and other fields specific for each Action Modified: trunk/esb/docs/esb_ref_guide/en-US/esb_support.xml =================================================================== --- trunk/esb/docs/esb_ref_guide/en-US/esb_support.xml 2010-03-18 15:59:15 UTC (rev 20906) +++ trunk/esb/docs/esb_ref_guide/en-US/esb_support.xml 2010-03-18 17:19:35 UTC (rev 20907) @@ -1,535 +1,535 @@ -<?xml version="1.0" encoding="UTF-8"?> -<chapter id="esb_support" role="updated"> - <?dbhtml filename="esb_support.html"?> - <chapterinfo> - <keywordset> - <keyword>JBoss Developer Studio</keyword> - <keyword>Eclipse</keyword> - <keyword>ESB</keyword> - <keyword>Java</keyword> - <keyword>JBoss</keyword> - </keywordset> - </chapterinfo> - - <title>ESB Support</title> - - <para>In this section we will focus on all concepts that <property>JBoss Tools</property> - integrate for working with JBoss ESB.</para> - - <section> - <title>ESB Tools Installation</title> - - <para>This chapter will provide you with the information on how to install - JBoss ESB plugin into Eclipse.</para> - - <para>ESB Tools come as one module of JBoss Tools project. Since ESB Tools have a - dependence on other JBoss Tools modules we recommend you to install a bundle - of all <ulink url="http://labs.jboss.com/tools/download.html">JBoss - Tools plug-ins</ulink>. You can find all necessary installation instructions on JBoss Wiki in the <ulink url="http://labs.jboss.com/wiki/InstallingJBossTools" - >InstallingJBossTools</ulink> section.</para> - </section> - - <section> - <title>Creating a ESB Project</title> - <para>In this chapter we suggest a step-by-step walk-through of creating a new - ESB project. Let&apos;s try to create a new JBoss ESB project.</para> - - <para>We will show you how to use the ESB Project Creation wizard for creating a new ESB project and setting basic ESB classpath.</para> - - <para>Select <emphasis> - <property>File &gt;New &gt; Project...</property> - </emphasis> in the main menu bar or context menu for selected project and - then <emphasis> - <property>ESB &gt; ESB Project</property> - </emphasis> in the dialog opened:</para> - - <figure> - <title>Select a Wizard dialog</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/esb_project/01_create_esb_project.png"/> - </imageobject> - </mediaobject> - </figure> - - <para> Clicking <emphasis> - <property>Next</property> - </emphasis> brings you to the JBoss ESB Project wizard page where a project name, ESB version and target JBoss Runtime are to be specified. Specify, for example, <emphasis> - <property>helloworld</property> - </emphasis> as a Project name and accept the default ESB version.</para> - <figure> - <title>JBoss ESB Project wizard</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/esb_project/02_create_esb_project.png"/> - </imageobject> - </mediaobject> - </figure> - <para>By clicking <emphasis>Modify</emphasis> button you can open <emphasis>Project Facets Wizard</emphasis> page,where you can select - facets that should be enabled for this project. - On the <emphasis>Project Facets Wizard</emphasis> page you can also configure runtime for the application</para> - <figure> - <title>Project Facets Wizard</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/esb_project/02a_create_esb_project.png"/> - </imageobject> - </mediaobject> - </figure> - <para>Next step provides you an opportunity to configure your project for building a java application</para> - - <para> Clicking <emphasis> - <property>Next</property> on this form - </emphasis> brings you to the ESB facet installation page where you can - specify Java Source Directory and ESB Content Directory. ESB Content Directory is a folder that contains the most of - artifacts that an ESB archive needs. You also can configure ESB libraries to the project by selecting a ESB runtime using one of the options: - </para> - <para>1. Use <emphasis> - <property>Server Supplied ESB Runtime</property> - </emphasis> - - </para> - <para> 2. Select a ESB runtime from the JBoss ESB runtime list predefined in the preferences. If you choose the first option, make sure that the project has the Target JBoss Runtime set and this runtime has a ESB runtime installed. - </para> - <para>3. Choose ESB Config Vertion. From the version 3.1.0 JBoss ESB Tools supports three different jboss-esb.xsd versions: jbossesb-1.0.1.xsd, jbossesb-1.1.0.xsd and jbossesb-1.2.0.xsd.</para> - <note><title>Note:</title> - <para>If you use ESB 4.7 you should select jbossesb-1.2.0.xsd.</para></note> - <figure> - <title>Install ESB facet step</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/esb_project/03_create_esb_project.png"/> - </imageobject> - </mediaobject> - </figure> - <para>Click <emphasis> - <property>Finish</property> - </emphasis> and a ESB project with the default <emphasis><property>jboss-esb.xml</property></emphasis> - will be created. </para> - - <figure> - <title>The generated ESB project structure</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/esb_project/04_create_esb_project.png"/> - </imageobject> - </mediaobject> - </figure> - - </section> - - <section id="ESB_project_wizard" xreflabel="here"> - <title>Creating ESB Project using JBoss Tools Project Examples Wizard</title> - <para>JBoss Tools provides a Project Example wizard that is an easy way for users to create some kinds of projects to be used as examples with some predefined structure. Let's start - creating a ESB project using this wizard.</para> - - <para>Before creating a ESB project example create JBoss Runtime with name <emphasis><property> - JBoss 4.2 Runtime</property></emphasis>, it will be used by your ESB project example. </para> - - <para>Select <emphasis> - <property>File &gt;New &gt; Others </property> - </emphasis> , in the main menu bar or context menu for selected project and - then <emphasis> - <property>JBoss Tools &gt; Project Examples</property> - </emphasis> in the New dialog:</para> - - <figure> - <title>Select a wizard - Project Examples</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/esb_project/05_esb_project_example.png"/> - </imageobject> - </mediaobject> - </figure> - - <para> Clicking <emphasis> - <property>Next</property> - </emphasis> brings you to the wizard page where you can select a ESB project example from the example list. - Every ESB example has two projects, one is a ESB project and another is a Java project used to test the ESB project.</para> - <para>Here is a list of ready examples available:</para> - - <itemizedlist> - - <listitem><para><emphasis role="bold">JBoss ESB HelloWorld Example</emphasis> - demonstrates the minimal files necessary to make a basic ESB component execute as well as to prove that the ESB os properly configured.</para></listitem> - <listitem><para><emphasis role="bold">JBoss ESB HelloWorld Action Example</emphasis> - demonstrates the use of multiple action invocations from a single configuration. You can use a single Action class and make multiple method calls or use multiple Action classes. </para></listitem> - <listitem><para><emphasis role="bold">JBoss ESB HelloWorld File Action Example</emphasis> - demonstrates using the File gateway feature of the JBoss ESB. Files that are found in a particular directory with a particular extension are sent to a JMS queue with actions for processing.</para></listitem> - <listitem><para><emphasis role="bold">JBoss ESB Web Service consumer1 Example</emphasis> - demonstrates how to consume a 181 Web Service in an ESB action.</para></listitem> - <listitem><para><emphasis role="bold">JBoss ESB Web Service producer Example</emphasis> - demonstrates how to deploy a JSR181 Webservice endpoint on JBossESB using the SOAPProcessor action.</para></listitem> - <listitem><para><emphasis role="bold">JBoss ESB Smooks CSV -&gt; XML Example</emphasis> - demonstrates how to transform a comma separated value (CSV) file to an XML.</para></listitem> - <listitem><para><emphasis role="bold">JBoss ESB Smooks XML -&gt; POJO Example</emphasis> - demonstrates the use of Smooks performing a simple transformation by converting an XML file into Java POJOs.</para></listitem> - <listitem><para><emphasis role="bold">JBoss ESB Smooks XML -&gt; XML date-manipulation Example</emphasis> - demonstrates how to manually define and apply a Message Transformation within JBoss ESB.</para></listitem> - <listitem><para><emphasis role="bold">JBoss ESB Smooks XML -&gt; XML Example</emphasis> - a very basic example of how to manually define and apply a Message Transformation within JBoss ESB. It applies a very simple XSLT to a SampleOrder.xml message and prints the before and after XML to the console. </para></listitem> - - </itemizedlist> - - - - <para>We will take as our example <emphasis><property>JBoss ESB HelloWorld Example</property> </emphasis> ESB and Client project:</para> - - - <figure> - <title>JBoss Tools ESB Project Examples</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/esb_project/06_esb_project_example.png"/> - </imageobject> - </mediaobject> - </figure> - - - <para>Choose them using the Ctrl button and then click - <emphasis><property>Finish</property></emphasis>. As a result you will get two projects created:</para> - <figure> - <title>JBoss ESB Project Examples: helloworld and helloworld_testclient</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/esb_project/07_esb_project_example.png"/> - </imageobject> - </mediaobject> - </figure> - - <para> Deploy the HelloWorld ESB project and run a test class in the client Java project to see the test result in the Console view.</para> - </section> - - <section> - <title>Deploying a ESB Project</title> - <para>In this chapter you will see how to deploy a ESB project using the WTP deployment framework.</para> - - <para>Before deploying the project, open the Servers view by selecting <emphasis><property>Window &gt; Show View &gt; Other &gt; - Server &gt; Servers</property></emphasis>, - create a JBoss Server in the Servers view and start it, and then right click the created JBoss server, - select <emphasis><property> </property> Add and Remove Projects</emphasis>, - and add the ESB projects you want to deploy from the left side to the right side in the opened dialog. </para> - - <figure> - <title>Add and Remove Projects</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/esb_project/08_esb_project_deploy.png"/> - </imageobject> - </mediaobject> - </figure> - - <para>Click <emphasis><property>Finish</property> </emphasis> to add the project to the server. - You also can drag the ESB project from the Project View to the server.</para> - - <figure> - <title>Servers view</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/esb_project/09_esb_runtime_new.png"/> - </imageobject> - </mediaobject> - </figure> - - <para>Thus, you have just added the ESB project to the JBoss server module list. Right click the JBoss Server and select <emphasis><property>Publish</property></emphasis> to publish the project on the server. - You can check the deploying result in the Console view.</para> - <para>The <emphasis><property>Run</property></emphasis> and <emphasis><property>Debug</property></emphasis> options work on ESB projects causing a (re)deploy for a user designated server.</para> - <para>You can also use the "Finger touch" for a quick restart of the project without restarting the server:</para> - <figure> - <title>Finger Touch button</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/esb_project/23_finger_touch.png"/> - </imageobject> - </mediaobject> - </figure> - <para>The "Finger" touches descriptors dependent on project (i.e. web.xml for WAR, application.xml for EAR) and now it is also available for jboss-esb.xml in ESB projects.</para> - <para>You can also deploy your ESB project as an .esb archive. Right-click on the project, choose <emphasis><property>Export</property></emphasis>:</para> - - <figure> - <title>Export of ESB project</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/esb_project/24_export_button.png"/> - </imageobject> - </mediaobject> - </figure> - - <para>Choose <emphasis><property>ESB</property></emphasis> &gt; <emphasis><property>ESB File</property></emphasis> and click <emphasis><property>Next</property></emphasis>:</para> - - <figure><title>Choosing ESB File</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/esb_project/25_esb_file.png"/> - </imageobject> - </mediaobject> - </figure> - - <para>And finally export the ESB project to the file system: choose the destination, choose the target runtime if need a specific one and make the appropriate settings for the archive. Then click <emphasis><property>Finish</property></emphasis>.</para> - - <figure><title>ESB Export</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/esb_project/26_esb_export.png"/> - </imageobject> - </mediaobject> - </figure> - - <para>Your project is deployed as an .esb archive.</para> - <para>An ESB archive can be created for ESB projects only. It is also possible to deploy an .esb archive to a JBoss AS based server with JBoss ESB installed.</para> - - - </section> - - <section id="creating_esb_file"> - <title>Creating a ESB File</title> - <para>In this chapter we suggest a step-by-step walk-through of creating your own - simple file. Let&apos;s try to organize a new ESB file.</para> - - <para>We will show you how to use the Creation wizard for creating a new ESB file.</para> - - <para>At first you should open any project. Select <emphasis> - <property>File &gt;New &gt; Other...</property> - </emphasis> in the main menu bar or context menu for selected project and - then <emphasis> - <property>ESB &gt; ESB File</property> - </emphasis> in the New dialog:</para> - - <figure> - <title>Select a wizard - ESB File</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/esb_support/01_create_esb.png"/> - </imageobject> - </mediaobject> - </figure> - - <para> Clicking <emphasis> - <property>Next</property> - </emphasis> brings you to the wizard page where a folder, a name and a version for the file should be specified. Choose, for example, <emphasis> - <property>jboss-esb.xml</property> - </emphasis> as the name and accept the selected projects folder and the default - version.</para> - - <note><title>Note:</title> - <para>From the version 3.1.0 JBoss ESB Tools supports three different jboss-esb.xsd versions: jbossesb-1.0.1.xsd, jbossesb-1.1.0.xsd and jbossesb-1.2.0.xsd. - If you use ESB 4.7 you should select jbossesb-1.2.0.xsd. - </para> - </note> - <figure> - <title>Folder, Name and Version for ESB file</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/esb_support/02_create_esb.png"/> - </imageobject> - </mediaobject> - </figure> - - <para>Thus, your file will be created in the selected projects folder by default. If - you want to change the folder for your future file click <emphasis> - <property>Browse...</property> - </emphasis> button to set needed folder or simply type it.</para> - - <para>Clicking on <emphasis> - <property>Finish</property> - </emphasis> results in the file being generated. The wizard creates one xml - file.</para> - - </section> - <section id="creating_esb_action"> - <title>Creating a ESB Action</title> - <para>From this chapter you will find out how to create a <emphasis><property>ESB Action Java File</property></emphasis>.</para> - <para>At first you need to open a <property>ESB</property> or simple <property>Java</property> project. Then you should select <emphasis><property>File > New>Other</property></emphasis> in the main menu or from the context project menu. Then click <emphasis><property>ESB > ESB Action</property></emphasis> in the <emphasis><property>New </property></emphasis> dialog.</para> - <figure> - <title>Select a wizard - ESB Action</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/esb_support/03_create_esb.png"/> - </imageobject> - - </mediaobject> - </figure> - <para>After that click <emphasis><property>Next</property></emphasis> and you will be brought to the <emphasis><property>New ESB Action</property></emphasis> wizard. In this wizard the class name should be specified, also you can set a package or add a interface as for any Java class.</para> - <figure> - <title>New ESB Action wizard</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/esb_support/04_create_esb.png"/> - </imageobject> - - </mediaobject> - </figure> - <para>As a result, the <property>ESB Action Java File</property> will be created in the selected package and it will have <property>org.jboss.soa.esb.actions.AbstractActionPipelineProcessor </property>as superclass. </para> - <para>Clicking on <emphasis><property>Finish</property></emphasis> will generate the <property>ESB Action</property> class. Also this class will become available in <property>ESB Editor</property> wizards.</para> - </section> - - <section role="updated"> - <title>Configuring ESB Runtime in Preferences</title> - <para>In this chapter you will know how to predefine a JBoss ESB runtime on the Preferences page.</para> - - <para>You may already know, there are two ways to set JBoss ESB runtime when creating a ESB project, - one is to use the project target JBoss runtime, and another is to select a JBoss ESB runtime predefined in JBoss Tools preferences. - Let's configure it.</para> - - <para>Select <emphasis> - <property>Window &gt;Preferences &gt; JBoss Tools &gt; JBoss ESB Runtime</property> - </emphasis>, to open the JBoss ESB Runtime Preferences page where you can add, remove and Edit a JBoss ESB runtime.</para> - - <figure> - <title>JBoss ESB Runtimes</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/esb_project/10_esb_runtime.png"/> - </imageobject> - </mediaobject> - </figure> - - <para> Select <emphasis><property>Add</property></emphasis> to open a dialog where you can specify the JBoss ESB runtime location, name and version number. It's also possible to define configuration if you point the home location to a Jboss AS or SOA-p, in case you select a standalone ESB runtime location, the configuration combo will be empty and should be ignored. - You can also customize the libraries of the runtime by checking the <emphasis><property>Customize JBoss ESB Runtime jars</property> </emphasis> checkbox. </para> - - <figure> - <title>Configure new JBoss ESB Runtime</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/esb_project/11_esb_runtime_new.png"/> - </imageobject> - </mediaobject> - </figure> - - <para>The new JBoss ESB Runtime will be configured. Click <emphasis> <property>OK</property> </emphasis> to finish and save the preferences. - You can use the configuration when creating a JBoss ESB project. </para> - <para>When a ESB runtime is configured for your ESB project you are able to change it to any other using the classpath container page for ESB runtime. To do that, turn to the Package Explorer view and right-click the "JBoss ESB Runtime" library. Select <emphasis><property>Properties</property></emphasis> and a table listing all available JBoss ESB runtimes will appear:</para> - - <figure> - <title>Classpath Container Page to change ESB runtime</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/esb_project/20_classpath_container.png"/> - </imageobject> - </mediaobject> - </figure> - - - - <para>Choose one of them to set to the ESB project and click <emphasis><property>Ok</property></emphasis>.</para> - <para>ESB container allows Source and JavaDoc locations to be set via the Properties dialog on each contained .jar: right-click on any .jar file, select <emphasis><property>Properties</property></emphasis>. Choose <emphasis><property>Java Source Attachment</property></emphasis> and select location (folder, JAR or zip) containing new source for the chosen .jar using one of the suggested options (workspace, external folder or file) or enter the path manually:</para> - - <figure> - <title>Classpath Container: Java Source Attachment</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/esb_project/21_source.png"/> - </imageobject> - </mediaobject> - </figure> - <para>Click on <emphasis><property>Apply</property></emphasis> and then on <emphasis><property>Ok</property></emphasis>.</para> - <para>To change Javadoc Location choose <emphasis><property>Javadoc Location</property></emphasis> and specify URL to the documentation generated by Javadoc. The Javadoc location will contain a file called <emphasis><property>package-list</property></emphasis>:</para> - - <figure> - <title>Classpath Container: Javadoc Location</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/esb_project/22_Javadoc.png"/> - </imageobject> - </mediaobject> - </figure> - <para>Click on <emphasis><property>Apply</property></emphasis> and then on <emphasis><property>Ok</property></emphasis>.</para> - - </section> - - - <section id="using_SOA"> - <title>Using and Configuring SOA Platform</title> - - <para>In this chapter you will know what is JBoss Enterprise SOA Platform and how you can configure it to use for your ESB projects. </para> - - <para>JBoss Enterprise SOA Platform delivers a flexible, standards-based platform to integrate applications, SOA services, business events and automate business processes. The SOA Platform integrates specific versions of JBoss ESB, jBPM, Drools and the JBoss Enterprise Application Platform that are certified to work together in a single supported enterprise distribution.</para> - <para>Having configured JBoss Enterprise SOA Platform for your ESB project you don't need to install and configure ESB server and runtime as they are already included.</para> - - <para>Check here to find more details on the platform: <ulink url="http://www.jboss.com/products/platforms/soa">JBoss Enterprise SOA Platform</ulink> and <ulink url="http://www.jboss.com/products/platforms/soa/components">... Enterprise SOA Platform Component Details</ulink>.</para> - <para>You can find out what is SOA here: <ulink url="http://www.jboss.org/jbossesb/resources/SOABasics.html">... of SOA</ulink> and <ulink url="http://www.jboss.org/jbossesb/resources/SOAEOA.html">SOA and EOA</ulink>.</para> - - <para>To configure the JBoss Enterprise SOA platform select <emphasis> - <property>Window &gt; Preferences &gt; Server &gt; Runtime Environments</property></emphasis>, that will open the Server Runtime Environments Preferences page where you can add, remove and edit a Server Runtime Environment.</para> - - <figure> - <title>Configure new Server Runtime Environment</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/esb_project/13NewServerRuntimeEnv.png"/> - </imageobject> - </mediaobject> - </figure> - - <para>Select <emphasis><property>Add</property></emphasis>, choose <emphasis><property>JBoss 4.2 Runtime</property></emphasis> as a type of runtime environment, check the <emphasis><property>Create a new local server</property></emphasis> checkbox and click <emphasis><property>Next</property></emphasis>:</para> - <figure> - <title>Type of Server Runtime Environment</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/esb_project/14typeOfRuntime.png"/> - </imageobject> - </mediaobject> - </figure> - - <para>On the next step you can specify a name of the server runtime environment and browse to its location. Click <emphasis><property>Finish</property></emphasis> to add the server runtime environment.</para> - - - <figure> - <title>New Server Runtime Environment Details</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/esb_project/15AddNew.png"/> - </imageobject> - </mediaobject> - </figure> - <para>Now you have your SOA platform configured. To check the configuration create a ESB Project using instructions described <xref linkend="ESB_project_wizard"/>. As a result you will have two projects created:</para> - - <figure> - <title>Helloworld Projects Created</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/esb_project/16HelloworldProjects.png"/> - </imageobject> - </mediaobject> - </figure> - <para>Then you will need to add JBoss ESB libraries to your projects to configure the SOA server runtime exactly for your projects. Right-click on your project, select <emphasis><property>Build Path &gt; Add Libraries</property></emphasis>:</para> - - <figure> - <title>Add Libraries</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/esb_project/17_Add_new_libraries.png"/> - </imageobject> - </mediaobject> - </figure> - - <para>Choose <emphasis><property>JBoss ESB Libraries</property></emphasis> and click <emphasis><property>Next</property></emphasis>:</para> - - <figure> - <title>ESB Libraries</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/esb_project/18_select_libraries.png"/> - </imageobject> - </mediaobject> - </figure> - - <para>Select the necessary runtime to add to the project classpath:</para> - - - <figure> - <title>Select a ESB runtime</title> - <mediaobject> - <imageobject> - <imagedata fileref="images/esb_project/19_select_runtime.png"/> - </imageobject> - </mediaobject> - </figure> - <para>Click <emphasis><property>Finish</property></emphasis>.</para> - <para>Now you can deploy your Helloworld project to the server and run a test class in the client Java project to see the test result in the Console view.</para> - - - -</section> - - - - - - - - - - -</chapter> +<?xml version="1.0" encoding="UTF-8"?> +<chapter id="esb_support" role="updated"> + <?dbhtml filename="esb_support.html"?> + <chapterinfo> + <keywordset> + <keyword>JBoss Developer Studio</keyword> + <keyword>Eclipse</keyword> + <keyword>ESB</keyword> + <keyword>Java</keyword> + <keyword>JBoss</keyword> + </keywordset> + </chapterinfo> + + <title>ESB Support</title> + + <para>In this section we will focus on all concepts that <property>JBoss Tools</property> + integrate for working with JBoss ESB.</para> + + <section> + <title>ESB Tools Installation</title> + + <para>This chapter will provide you with the information on how to install + JBoss ESB plugin into Eclipse.</para> + + <para>ESB Tools come as one module of JBoss Tools project. Since ESB Tools have a + dependence on other JBoss Tools modules we recommend you to install a bundle + of all <ulink url="http://labs.jboss.com/tools/download.html">JBoss + Tools plug-ins</ulink>. You can find all necessary installation instructions on JBoss Wiki in the <ulink url="http://labs.jboss.com/wiki/InstallingJBossTools" + >InstallingJBossTools</ulink> section.</para> + </section> + + <section> + <title>Creating a ESB Project</title> + <para>In this chapter we suggest a step-by-step walk-through of creating a new + ESB project. Let&apos;s try to create a new JBoss ESB project.</para> + + <para>We will show you how to use the ESB Project Creation wizard for creating a new ESB project and setting basic ESB classpath.</para> + + <para>Select <emphasis> + <property>File &gt;New &gt; Project...</property> + </emphasis> in the main menu bar or context menu for selected project and + then <emphasis> + <property>ESB &gt; ESB Project</property> + </emphasis> in the dialog opened:</para> + + <figure> + <title>Select a Wizard dialog</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/esb_project/01_create_esb_project.png"/> + </imageobject> + </mediaobject> + </figure> + + <para> Clicking <emphasis> + <property>Next</property> + </emphasis> brings you to the JBoss ESB Project wizard page where a project name, ESB version and target JBoss Runtime are to be specified. Specify, for example, <emphasis> + <property>helloworld</property> + </emphasis> as a Project name and accept the default ESB version.</para> + <figure> + <title>JBoss ESB Project wizard</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/esb_project/02_create_esb_project.png"/> + </imageobject> + </mediaobject> + </figure> + <para>By clicking <emphasis>Modify</emphasis> button you can open <emphasis>Project Facets Wizard</emphasis> page,where you can select + facets that should be enabled for this project. + On the <emphasis>Project Facets Wizard</emphasis> page you can also configure runtime for the application</para> + <figure> + <title>Project Facets Wizard</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/esb_project/02a_create_esb_project.png"/> + </imageobject> + </mediaobject> + </figure> + <para>Next step provides you an opportunity to configure your project for building a java application</para> + + <para> Clicking <emphasis> + <property>Next</property> on this form + </emphasis> brings you to the ESB facet installation page where you can + specify Java Source Directory and ESB Content Directory. ESB Content Directory is a folder that contains the most of + artifacts that an ESB archive needs. You also can configure ESB libraries to the project by selecting a ESB runtime using one of the options: + </para> + <para>1. Use <emphasis> + <property>Server Supplied ESB Runtime</property> + </emphasis> + + </para> + <para> 2. Select a ESB runtime from the JBoss ESB runtime list predefined in the preferences. If you choose the first option, make sure that the project has the Target JBoss Runtime set and this runtime has a ESB runtime installed. + </para> + <para>3. Choose ESB Config Vertion. From the version 3.1.0 JBoss ESB Tools supports three different jboss-esb.xsd versions: jbossesb-1.0.1.xsd, jbossesb-1.1.0.xsd and jbossesb-1.2.0.xsd.</para> + <note><title>Note:</title> + <para>If you use ESB 4.7 you should select jbossesb-1.2.0.xsd.</para></note> + <figure> + <title>Install ESB facet step</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/esb_project/03_create_esb_project.png"/> + </imageobject> + </mediaobject> + </figure> + <para>Click <emphasis> + <property>Finish</property> + </emphasis> and a ESB project with the default <emphasis><property>jboss-esb.xml</property></emphasis> + will be created. </para> + + <figure> + <title>The generated ESB project structure</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/esb_project/04_create_esb_project.png"/> + </imageobject> + </mediaobject> + </figure> + + </section> + + <section id="ESB_project_wizard" xreflabel="here"> + <title>Creating ESB Project using JBoss Tools Project Examples Wizard</title> + <para>JBoss Tools provides a Project Example wizard that is an easy way for users to create some kinds of projects to be used as examples with some predefined structure. Let's start + creating a ESB project using this wizard.</para> + + <para>Before creating a ESB project example create JBoss Runtime with name <emphasis><property> + JBoss 4.2 Runtime</property></emphasis>, it will be used by your ESB project example. </para> + + <para>Select <emphasis> + <property>File &gt;New &gt; Others </property> + </emphasis> , in the main menu bar or context menu for selected project and + then <emphasis> + <property>JBoss Tools &gt; Project Examples</property> + </emphasis> in the New dialog:</para> + + <figure> + <title>Select a wizard - Project Examples</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/esb_project/05_esb_project_example.png"/> + </imageobject> + </mediaobject> + </figure> + + <para> Clicking <emphasis> + <property>Next</property> + </emphasis> brings you to the wizard page where you can select a ESB project example from the example list. + Every ESB example has two projects, one is a ESB project and another is a Java project used to test the ESB project.</para> + <para>Here is a list of ready examples available:</para> + + <itemizedlist> + + <listitem><para><emphasis role="bold">JBoss ESB HelloWorld Example</emphasis> - demonstrates the minimal files necessary to make a basic ESB component execute as well as to prove that the ESB is properly configured.</para></listitem> + <listitem><para><emphasis role="bold">JBoss ESB HelloWorld Action Example</emphasis> - demonstrates the use of multiple action invocations from a single configuration. You can use a single Action class and make multiple method calls or use multiple Action classes. </para></listitem> + <listitem><para><emphasis role="bold">JBoss ESB HelloWorld File Action Example</emphasis> - demonstrates using the File gateway feature of the JBoss ESB. Files that are found in a particular directory with a particular extension are sent to a JMS queue with actions for processing.</para></listitem> + <listitem><para><emphasis role="bold">JBoss ESB Web Service consumer1 Example</emphasis> - demonstrates how to consume a 181 Web Service in an ESB action.</para></listitem> + <listitem><para><emphasis role="bold">JBoss ESB Web Service producer Example</emphasis> - demonstrates how to deploy a JSR181 Webservice endpoint on JBossESB using the SOAPProcessor action.</para></listitem> + <listitem><para><emphasis role="bold">JBoss ESB Smooks CSV -&gt; XML Example</emphasis> - demonstrates how to transform a comma separated value (CSV) file to an XML.</para></listitem> + <listitem><para><emphasis role="bold">JBoss ESB Smooks XML -&gt; POJO Example</emphasis> - demonstrates the use of Smooks performing a simple transformation by converting an XML file into Java POJOs.</para></listitem> + <listitem><para><emphasis role="bold">JBoss ESB Smooks XML -&gt; XML date-manipulation Example</emphasis> - demonstrates how to manually define and apply a Message Transformation within JBoss ESB.</para></listitem> + <listitem><para><emphasis role="bold">JBoss ESB Smooks XML -&gt; XML Example</emphasis> - a very basic example of how to manually define and apply a Message Transformation within JBoss ESB. It applies a very simple XSLT to a SampleOrder.xml message and prints the before and after XML to the console. </para></listitem> + + </itemizedlist> + + + + <para>We will take as our example <emphasis><property>JBoss ESB HelloWorld Example</property> </emphasis> ESB and Client project:</para> + + + <figure> + <title>JBoss Tools ESB Project Examples</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/esb_project/06_esb_project_example.png"/> + </imageobject> + </mediaobject> + </figure> + + + <para>Choose them using the Ctrl button and then click + <emphasis><property>Finish</property></emphasis>. As a result you will get two projects created:</para> + <figure> + <title>JBoss ESB Project Examples: helloworld and helloworld_testclient</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/esb_project/07_esb_project_example.png"/> + </imageobject> + </mediaobject> + </figure> + + <para> Deploy the HelloWorld ESB project and run a test class in the client Java project to see the test result in the Console view.</para> + </section> + + <section> + <title>Deploying a ESB Project</title> + <para>In this chapter you will see how to deploy a ESB project using the WTP deployment framework.</para> + + <para>Before deploying the project, open the JBoss Server View by selecting <emphasis><property>Window &gt; Show View &gt; Other &gt; + Server &gt; JBoss Server View</property></emphasis>, + create a JBoss Server in the Server view and start it, and then right click the created JBoss server, + select <emphasis><property> </property> Add and Remove Projects</emphasis>, + and add the ESB projects you want to deploy from the left side to the right side in the opened dialog. </para> + + <figure> + <title>Add and Remove Projects</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/esb_project/08_esb_project_deploy.png"/> + </imageobject> + </mediaobject> + </figure> + + <para>Click <emphasis><property>Finish</property> </emphasis> to add the project to the server. + You also can drag the ESB project from the Project View to the server.</para> + + <figure> + <title>JBoss Server View</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/esb_project/09_esb_runtime_new.png"/> + </imageobject> + </mediaobject> + </figure> + + <para>Thus, you have just added the ESB project to the JBoss server module list. Right click the JBoss Server and select <emphasis><property>Publish</property></emphasis> to publish the project on the server. + You can check the deploying result in the Console view.</para> + <para>The <emphasis><property>Run</property></emphasis> and <emphasis><property>Debug</property></emphasis> options work on ESB projects causing a (re)deploy for a user designated server.</para> + <para>You can also use the "Finger touch" for a quick restart of the project without restarting the server:</para> + <figure> + <title>Finger Touch button</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/esb_project/23_finger_touch.png"/> + </imageobject> + </mediaobject> + </figure> + <para>The "Finger" touches descriptors dependent on project (i.e. web.xml for WAR, application.xml for EAR) and now it is also available for jboss-esb.xml in ESB projects.</para> + <para>You can also deploy your ESB project as an .esb archive. Right-click on the project, choose <emphasis><property>Export</property></emphasis>:</para> + + <figure> + <title>Export of ESB project</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/esb_project/24_export_button.png"/> + </imageobject> + </mediaobject> + </figure> + + <para>Choose <emphasis><property>ESB</property></emphasis> &gt; <emphasis><property>ESB File</property></emphasis> and click <emphasis><property>Next</property></emphasis>:</para> + + <figure><title>Choosing ESB File</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/esb_project/25_esb_file.png"/> + </imageobject> + </mediaobject> + </figure> + + <para>And finally export the ESB project to the file system: choose the destination, choose the target runtime if need a specific one and make the appropriate settings for the archive. Then click <emphasis><property>Finish</property></emphasis>.</para> + + <figure><title>ESB Export</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/esb_project/26_esb_export.png"/> + </imageobject> + </mediaobject> + </figure> + + <para>Your project is deployed as an .esb archive.</para> + <para>An ESB archive can be created for ESB projects only. It is also possible to deploy an .esb archive to a JBoss AS based server with JBoss ESB installed.</para> + + + </section> + + <section id="creating_esb_file"> + <title>Creating a ESB File</title> + <para>In this chapter we suggest a step-by-step walk-through of creating your own + simple file. Let&apos;s try to organize a new ESB file.</para> + + <para>We will show you how to use the Creation wizard for creating a new ESB file.</para> + + <para>At first you should open any project. Select <emphasis> + <property>File &gt;New &gt; Other...</property> + </emphasis> in the main menu bar or context menu for selected project and + then <emphasis> + <property>ESB &gt; ESB File</property> + </emphasis> in the New dialog:</para> + + <figure> + <title>Select a wizard - ESB File</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/esb_support/01_create_esb.png"/> + </imageobject> + </mediaobject> + </figure> + + <para> Clicking <emphasis> + <property>Next</property> + </emphasis> brings you to the wizard page where a folder, a name and a version for the file should be specified. Choose, for example, <emphasis> + <property>jboss-esb.xml</property> + </emphasis> as the name and accept the selected projects folder and the default + version.</para> + + <note><title>Note:</title> + <para>From the version 3.1.0 JBoss ESB Tools supports three different jboss-esb.xsd versions: jbossesb-1.0.1.xsd, jbossesb-1.1.0.xsd and jbossesb-1.2.0.xsd. + If you use ESB 4.7 you should select jbossesb-1.2.0.xsd. + </para> + </note> + <figure> + <title>Folder, Name and Version for ESB file</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/esb_support/02_create_esb.png"/> + </imageobject> + </mediaobject> + </figure> + + <para>Thus, your file will be created in the selected projects folder by default. If + you want to change the folder for your future file click <emphasis> + <property>Browse...</property> + </emphasis> button to set needed folder or simply type it.</para> + + <para>Clicking on <emphasis> + <property>Finish</property> + </emphasis> results in the file being generated. The wizard creates one xml + file.</para> + + </section> + <section id="creating_esb_action"> + <title>Creating a ESB Action</title> + <para>From this chapter you will find out how to create a <emphasis><property>ESB Action Java File</property></emphasis>.</para> + <para>At first you need to open a <property>ESB</property> or simple <property>Java</property> project. Then you should select <emphasis><property>File > New>Other</property></emphasis> in the main menu or from the context project menu. Then click <emphasis><property>ESB > ESB Action</property></emphasis> in the <emphasis><property>New </property></emphasis> dialog.</para> + <figure> + <title>Select a wizard - ESB Action</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/esb_support/03_create_esb.png"/> + </imageobject> + + </mediaobject> + </figure> + <para>After that click <emphasis><property>Next</property></emphasis> and you will be brought to the <emphasis><property>New ESB Action</property></emphasis> wizard. In this wizard the class name should be specified, also you can set a package or add a interface as for any Java class.</para> + <figure> + <title>New ESB Action wizard</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/esb_support/04_create_esb.png"/> + </imageobject> + + </mediaobject> + </figure> + <para>As a result, the <property>ESB Action Java File</property> will be created in the selected package and it will have <property>org.jboss.soa.esb.actions.AbstractActionPipelineProcessor </property>as superclass. </para> + <para>Clicking on <emphasis><property>Finish</property></emphasis> will generate the <property>ESB Action</property> class. Also this class will become available in <property>ESB Editor</property> wizards.</para> + </section> + + <section role="updated"> + <title>Configuring ESB Runtime in Preferences</title> + <para>In this chapter you will know how to predefine a JBoss ESB runtime on the Preferences page.</para> + + <para>You may already know, there are two ways to set JBoss ESB runtime when creating a ESB project, + one is to use the project target JBoss runtime, and another is to select a JBoss ESB runtime predefined in JBoss Tools preferences. + Let's configure it.</para> + + <para>Select <emphasis> + <property>Window &gt;Preferences &gt; JBoss Tools &gt; JBoss ESB Runtime</property> + </emphasis>, to open the JBoss ESB Runtime Preferences page where you can add, remove and Edit a JBoss ESB runtime.</para> + + <figure> + <title>JBoss ESB Runtimes</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/esb_project/10_esb_runtime.png"/> + </imageobject> + </mediaobject> + </figure> + + <para> Select <emphasis><property>Add</property></emphasis> to open a dialog where you can specify the JBoss ESB runtime location, name and version number. It's also possible to define configuration if you point the home location to a Jboss AS or SOA-p, in case you select a standalone ESB runtime location, the configuration combo will be empty and should be ignored. + You can also customize the libraries of the runtime by checking the <emphasis><property>Customize JBoss ESB Runtime jars</property> </emphasis> checkbox. </para> + + <figure> + <title>Configure new JBoss ESB Runtime</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/esb_project/11_esb_runtime_new.png"/> + </imageobject> + </mediaobject> + </figure> + + <para>The new JBoss ESB Runtime will be configured. Click <emphasis> <property>OK</property> </emphasis> to finish and save the preferences. + You can use the configuration when creating a JBoss ESB project. </para> + <para>When a ESB runtime is configured for your ESB project you are able to change it to any other using the classpath container page for ESB runtime. To do that, turn to the Package Explorer view and right-click the "JBoss ESB Runtime" library. Select <emphasis><property>Properties</property></emphasis> and a table listing all available JBoss ESB runtimes will appear:</para> + + <figure> + <title>Classpath Container Page to change ESB runtime</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/esb_project/20_classpath_container.png"/> + </imageobject> + </mediaobject> + </figure> + + + + <para>Choose one of them to set to the ESB project and click <emphasis><property>Ok</property></emphasis>.</para> + <para>ESB container allows Source and JavaDoc locations to be set via the Properties dialog on each contained .jar: right-click on any .jar file, select <emphasis><property>Properties</property></emphasis>. Choose <emphasis><property>Java Source Attachment</property></emphasis> and select location (folder, JAR or zip) containing new source for the chosen .jar using one of the suggested options (workspace, external folder or file) or enter the path manually:</para> + + <figure> + <title>Classpath Container: Java Source Attachment</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/esb_project/21_source.png"/> + </imageobject> + </mediaobject> + </figure> + <para>Click on <emphasis><property>Apply</property></emphasis> and then on <emphasis><property>Ok</property></emphasis>.</para> + <para>To change Javadoc Location choose <emphasis><property>Javadoc Location</property></emphasis> and specify URL to the documentation generated by Javadoc. The Javadoc location will contain a file called <emphasis><property>package-list</property></emphasis>:</para> + + <figure> + <title>Classpath Container: Javadoc Location</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/esb_project/22_Javadoc.png"/> + </imageobject> + </mediaobject> + </figure> + <para>Click on <emphasis><property>Apply</property></emphasis> and then on <emphasis><property>Ok</property></emphasis>.</para> + + </section> + + + <section id="using_SOA"> + <title>Using and Configuring SOA Platform</title> + + <para>In this chapter you will know what is JBoss Enterprise SOA Platform and how you can configure it to use for your ESB projects. </para> + + <para>JBoss Enterprise SOA Platform delivers a flexible, standards-based platform to integrate applications, SOA services, business events and automate business processes. The SOA Platform integrates specific versions of JBoss ESB, jBPM, Drools and the JBoss Enterprise Application Platform that are certified to work together in a single supported enterprise distribution.</para> + <para>Having configured JBoss Enterprise SOA Platform for your ESB project you don't need to install and configure ESB server and runtime as they are already included.</para> + + <para>Check here to find more details on the platform: <ulink url="http://www.jboss.com/products/platforms/soa">JBoss Enterprise SOA Platform</ulink> and <ulink url="http://www.jboss.com/products/platforms/soa/components">... Enterprise SOA Platform Component Details</ulink>.</para> + <para>You can find out what is SOA here: <ulink url="http://www.jboss.org/jbossesb/resources/SOABasics.html">... of SOA</ulink> and <ulink url="http://www.jboss.org/jbossesb/resources/SOAEOA.html">SOA and EOA</ulink>.</para> + + <para>To configure the JBoss Enterprise SOA platform select <emphasis> + <property>Window &gt; Preferences &gt; Server &gt; Runtime Environments</property></emphasis>, that will open the Server Runtime Environments Preferences page where you can add, remove and edit a Server Runtime Environment.</para> + + <figure> + <title>Configure new Server Runtime Environment</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/esb_project/13NewServerRuntimeEnv.png"/> + </imageobject> + </mediaobject> + </figure> + + <para>Select <emphasis><property>Add</property></emphasis>, choose <emphasis><property>JBoss 4.2 Runtime</property></emphasis> as a type of runtime environment, check the <emphasis><property>Create a new local server</property></emphasis> checkbox and click <emphasis><property>Next</property></emphasis>:</para> + <figure> + <title>Type of Server Runtime Environment</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/esb_project/14typeOfRuntime.png"/> + </imageobject> + </mediaobject> + </figure> + + <para>On the next step you can specify a name of the server runtime environment and browse to its location. Click <emphasis><property>Finish</property></emphasis> to add the server runtime environment.</para> + + + <figure> + <title>New Server Runtime Environment Details</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/esb_project/15AddNew.png"/> + </imageobject> + </mediaobject> + </figure> + <para>Now you have your SOA platform configured. To check the configuration create a ESB Project using instructions described <xref linkend="ESB_project_wizard"/>. As a result you will have two projects created:</para> + + <figure> + <title>Helloworld Projects Created</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/esb_project/16HelloworldProjects.png"/> + </imageobject> + </mediaobject> + </figure> + <para>Then you will need to add JBoss ESB libraries to your projects to configure the SOA server runtime exactly for your projects. Right-click on your project, select <emphasis><property>Build Path &gt; Add Libraries</property></emphasis>:</para> + + <figure> + <title>Add Libraries</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/esb_project/17_Add_new_libraries.png"/> + </imageobject> + </mediaobject> + </figure> + + <para>Choose <emphasis><property>JBoss ESB Libraries</property></emphasis> and click <emphasis><property>Next</property></emphasis>:</para> + + <figure> + <title>ESB Libraries</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/esb_project/18_select_libraries.png"/> + </imageobject> + </mediaobject> + </figure> + + <para>Select the necessary runtime to add to the project classpath:</para> + + + <figure> + <title>Select a ESB runtime</title> + <mediaobject> + <imageobject> + <imagedata fileref="images/esb_project/19_select_runtime.png"/> + </imageobject> + </mediaobject> + </figure> + <para>Click <emphasis><property>Finish</property></emphasis>.</para> + <para>Now you can deploy your Helloworld project to the server and run a test class in the client Java project to see the test result in the Console view.</para> + + + +</section> + + + + + + + + + + +</chapter> \ No newline at end of file