<?xml version="1.0" encoding="UTF-8"?>
<chapter id="eclipse">
  <title>Eclipse plugin</title>
  
  <para>
    The IronJacamar Eclipse plugin features development tools used
    for developing resource adapter applications for the IronJacamar standalone distribution,
    WildFly or JBoss Enterprise Application Platform 6+.
  </para>

  <para>
    The plugin allows you to
    
    <itemizedlist>
      <listitem>
        Generate a resource adapter skeleton
      </listitem>
      <listitem>
        Generate a deployment descriptor for a resource adapter
      </listitem>
      <listitem>
        Validate a resource adapter
      </listitem>
      <listitem>
        Deploy a resource adapter to an IronJacamar server instance
      </listitem>
      <listitem>
        Deploy a deployment descriptor to an IronJacamar server instance
      </listitem>
    </itemizedlist>

  </para>

  <section id="eclipse_installation">
    <title>Installation of the plugin</title>

    <para>
      The plugin is installed by
    </para>
        
    <programlisting>
cp ironjacamar-eclipse.jar $ECLIPSE_HOME/plugins
    </programlisting>

    <para>
      on Un*x systems, or by
    </para>

    <programlisting>
copy ironjacamar-eclipse.jar %ECLIPSE_HOME%\plugins
    </programlisting>

    <para>
      on Windows.
    </para>

  </section>

  <section id="eclipse_configure">
    <title>Configuration of the plugin</title>

    <para>
      Open "Window-&gt;Preferences" and select the IronJacamar category.

    </para>

    <mediaobject>
      <imageobject>
        <imagedata fileref="images/eclipse-configuration.png" align="center"/>
      </imageobject>
    </mediaobject>
    
    <para>
      The IronJacamar home setting must point to the root directory of the IronJacamar installation, like
    </para>

    <programlisting>
/opt/ironjacamar-1.2.0.Final
    </programlisting>

    <para>
      in order to configure the plugin.
    </para>

    <para>
      The IronJacamar Eclipse plugin can deploy to a remote IronJacamar instance, by specifying the host and port settings.
    </para>

  </section>

  <section id="eclipse_toolbar">
    <title>The toolbar</title>
    <para>
      The IronJacamar Eclipse plugin provides a toolbar with deployment functionality.
    </para>

    <mediaobject>
      <imageobject>
        <imagedata fileref="images/eclipse-toolbar.png" align="center"/>
      </imageobject>
    </mediaobject>

  </section>

  <section id="eclipse_menu">
    <title>The menu</title>
    <para>
      The IronJacamar Eclipse plugin provides a menu with validation and deployment functionality.
    </para>

    <mediaobject>
      <imageobject>
        <imagedata fileref="images/eclipse-menu.png" align="center"/>
      </imageobject>
    </mediaobject>

  </section>

  <section id="eclipse_project">
    <title>Creating a new IronJacamar project</title>

    <para>
      A new IronJacamar project can be created by selecting File-&gt;New-&gt;Project... and go to the IronJacamar category. 
    </para>

    <para>
      Choose "IronJacamar 1.1 project" and follow the instructions to generate your resource adapter.
    </para>
    
    <mediaobject>
      <imageobject>
        <imagedata fileref="images/eclipse-new-project.png" align="center"/>
      </imageobject>
    </mediaobject>

    <section id="eclipse_project_name">
      <title>Project and package name</title>
     
      <mediaobject>
        <imageobject>
          <imagedata fileref="images/eclipse-new-project-name.png" align="center"/>
        </imageobject>
      </mediaobject>

      <para>    
        Sepcify the project name and package name for the project. You can also select the JCA specification version,
        the type of the resource adapter (Outbound/Inbound/Bidirectional), the transaction support level, if the resource adapter
        will support reauthentication and if annotations used be used for a JCA 1.6+ based resource adapter.
      </para>    

    </section>

    <section id="eclipse_project_ra">
      <title>Creating a ResourceAdapter</title>
     
      <mediaobject>
        <imageobject>
          <imagedata fileref="images/eclipse-new-project-ra.png" align="center"/>
        </imageobject>
      </mediaobject>
      
      <para>    
        You can choose to include a <code>ResourceAdapter</code> class if the JCA profile version is 1.5, 1.6 or 1.7
      </para>    

    </section>

    <section id="eclipse_project_outbound">
      <title>Creating a ManagedConnectionFactory</title>
      
      <mediaobject>
        <imageobject>
          <imagedata fileref="images/eclipse-new-project-outbound.png" align="center"/>
        </imageobject>
      </mediaobject>
      
      <para>    
        If the project is Outbound or Bidirectional then you can fill in the information for the outbound components.
      </para>    

    </section>

    <section id="eclipse_project_inbound">
      <title>Creating a MessageListener</title>
      
      <mediaobject>
        <imageobject>
          <imagedata fileref="images/eclipse-new-project-inbound.png" align="center"/>
        </imageobject>
      </mediaobject>
      
      <para>    
        If the project is Inbound or Bidirectional then you can fill in the information for the message listener and activation specification
        components.
      </para>    

    </section>

    <section id="eclipse_project_ao">
      <title>Creating an AdminObject</title>
     
      <mediaobject>
        <imageobject>
          <imagedata fileref="images/eclipse-new-project-ao.png" align="center"/>
        </imageobject>
      </mediaobject>
      
      <para>    
        This wizard creates an AdminObject for the project.
      </para>    

    </section>

    <section id="eclipse_project_build">
      <title>Selecting the build environment</title>
     
      <mediaobject>
        <imageobject>
          <imagedata fileref="images/eclipse-new-project-build.png" align="center"/>
        </imageobject>
      </mediaobject>
      
      <para>    
        This wizard will let you choose the build environment to use for your project. Currently IronJacamar supports the Apache Ant, Apache Ant + Apache Ivy or Maven build environments.
        If Apache Ant is selected, all library files will be copied from your IronJacamar installation.
      </para>    

      <note>
        <para>    
          Please make sure you have installed the Eclipse M2E plugin if you select Apache Maven as your build environment.
        </para>    
      </note>

    </section>

  </section>

  <section id="eclipse_validate">
    <title>Validate IronJacamar project</title>

    <para>
      The IronJacamar project can be validated by selecting it, and the Validate command in the toolbar will now be enabled. Click on the command to validate your project.
    </para>

    <para>
      Another way to validate the IronJacamar project is to right click on the project, and select IronJacamar-&gt;Validate.
    </para>

  </section>

  <section id="eclipse_deploy">
    <title>Deploying an IronJacamar project</title>

    <para>
      The IronJacamar Eclipse plugin provides a way to deploy files to an IronJacamar server.
    </para>

    <note>
      <para>
        Before any deploy operation, the IronJacamar server needs to be started, otherwise it will lead to an error dialog. 
        Please refer to <link linkend="startingthecontainer">this</link> for detail on how to start the IronJacamar server
      </para>
    </note>

    <section id="eclipse_deploy_rar">
      <title>Deploying a RAR file to an IronJacamar server</title>

      <para>
        Select the IronJacamar project you just created. The Deploy drop down command in the toolbar will be enabled. Click on the command and select 'Deploy rar'.
      </para>

      <para>
        Another way to deploy the RAR file is to right click on the project, and select IronJacamar-&gt;Deploy-&gt;Deploy rar from context menu
      </para>

      <para>
        The command will build the RAR file first if it doesn't exist, then try to connect the IronJacamar server to deploy it.
      </para>

    </section>

    <section id="eclipse_deploy_raxml">
      <title>Generate the -ra.xml and deploy it to IronJacamar server</title>

      <para>
        Select the IronJacamar project you just created. The Deploy drop down command in the toolbar will be enabled. Click on the command and select 'Deploy -ra.xml'.
      </para>

      <para>
        Another way to generate the -ra.xml file is to right click on the project, and select IronJacamar-&gt;Deploy-&gt;Deploy -ra.xml from context menu.
      </para>

      <para>
        The command will build the RAR file first if it does not exist, then pop up a wizard to generate the -ra.xml according to the RAR file.
      </para>

      <mediaobject>
        <imageobject>
          <imagedata fileref="images/eclipse-ra-version.png" align="center"/>
        </imageobject>
      </mediaobject>

      <para>
        In the first wizard page, selects version of the resource adapter. Some configurations may not be available when version is changed.
      </para>

      <mediaobject>
        <imageobject>
          <imagedata fileref="images/eclipse-ra-general.png" align="center"/>
        </imageobject>
      </mediaobject>

      <para>
        In the general information page, set up the transaction support, bootstrap context, bean validation groups and id if the version is 1.1+.
      </para>

      <mediaobject>
        <imageobject>
          <imagedata fileref="images/eclipse-ra-workmanager.png" align="center"/>
        </imageobject>
      </mediaobject>

      <para>
        From IronJacamar 1.1, a workmanager tab is added to configure workmanager security mappings.
      </para>

      <mediaobject>
        <imageobject>
          <imagedata fileref="images/eclipse-ra-mcf.png" align="center"/>
        </imageobject>
      </mediaobject>

      <para>
        There is a wizard page for each ManagedConnectionFactory if the resource adapter is outbound or bidirectional.
      </para>
      <para>
        The ManagedConnectionFactory can be activated by selecting the 'Activate' checkbox. 
      </para>

      <mediaobject>
        <imageobject>
          <imagedata fileref="images/eclipse-ra-mcf-pool.png" align="center"/>
        </imageobject>
      </mediaobject>

      <para>
        Configure connection pool in the 'pool configuration' tab.
      </para>

      <mediaobject>
        <imageobject>
          <imagedata fileref="images/eclipse-ra-mcf-pool-xa.png" align="center"/>
        </imageobject>
      </mediaobject>

      <para>
        Configure XA connection pool in the 'XA pool' sub tab.
      </para>

      <mediaobject>
        <imageobject>
          <imagedata fileref="images/eclipse-ra-mcf-pool-capacity.png" align="center"/>
        </imageobject>
      </mediaobject>

      <para>
        From IronJacamar 1.1 on, a capacity sub tab is added in 'pool configuration' tab to configure policy of connection pool
      </para>

      <mediaobject>
        <imageobject>
          <imagedata fileref="images/eclipse-ra-ao.png" align="center"/>
        </imageobject>
      </mediaobject>

      <para>
        There is a wizard page for each AdminObject if the resource adapter includes one or more instances.
      </para>

      <para>
        The AdminObject can be activated by selecting the 'Activate' checkbox.
      </para>

      <para>
        There is a miscellaneous page also.
      </para>

      <mediaobject>
        <imageobject>
          <imagedata fileref="images/eclipse-ra-mess.png" align="center"/>
        </imageobject>
      </mediaobject>

      <para>
        If the Deploy RAR first option is selected, the plugin will try to deploy the RAR file to the IronJacamar server first,
        then deploy the generated -ra.xml file.
      </para>

    </section>


  </section>
</chapter>
