bundles/org.eclipse.rap.doc/guide/articles/deployment.html - rap/org.eclipse.rap.tools - Git at Google

 <?xml version="1.0" encoding="UTF-8" ?>
 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
     "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
 <html xmlns="http://www.w3.org/1999/xhtml">
 <head>
   <meta name="copyright" content="Copyright (c) 2007, 2013 EclipseSource. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page."/>
   <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
   <title>Deployment</title>
   <link rel="stylesheet" href="../../../PRODUCT_PLUGIN/book.css" type="text/css"/>
 </head>
 <body>

   <h1>Deploying a RAP Application to a Servlet Container</h1>

   <p>
     The following tutorial shows how to create a <em>WAR</em> file that contains the
     <em>org.eclipse.rap.demo</em> project as a RAP application.
   </p>

   <p>
     Note: As with RCP applications there are a wide variety of possible configurations.
     What's given in this tutorial is just one possibility.
   </p>

   <p>
     As prerequisites we assume that you:
   </p>
   <ul>
     <li>
       are familiar with the bundles- and build information section of the
       <a href="http://www.eclipse.org/equinox/server/http_in_container.php">
       Equinox in a Servlet Container</a> document.
     </li>
     <li>
       have installed the WAR Products tooling from this p2 repository
       <a href="http://download.eclipse.org/releases/juno/">http://download.eclipse.org/releases/juno/</a>
       into your IDE. This tooling is part of <a href="http://eclipse.org/libra/">Libra</a> and not
       part of RAP. Anyway it can be used to deploy RAP applications in a very comfortable way.
     </li>
     <li>
       have set a target platform that contains RAP.
     </li>
   </ul>

   <h3>Import org.eclipse.rap.demo into your workspace</h3>
   <ul>
     <li>
       Open the <em class="UILabel">Plug-ins</em> view.
     </li>
     <li>
       Select the <em>org.eclipse.rap.demo</em> plug-in and use the command
       <em class="UILabel">Import As</em> &gt; <em class="UILabel">Source Project</em> from the context menu to import
       <em>org.eclipse.rap.demo</em> as a project in your workspace.
     </li>
   </ul>
   <img src="../images/import_rap_demo.png" alt="Import RAP demo project"/>

   <h3>Create a .warproduct configuration</h3>
   <p>
     Building a <em>WAR</em> file using the WAR Products tooling is centered around
     a <em>.warproduct</em> configuration. The <em>.warproduct</em> configuration is
     entirely managed by the WAR Products tooling to simplify war deployment. It's format
     is internal and is not intended to be read by tools other than the WAR Products tooling.
     To create a <em>.warproduct</em> configuration you can use a working launch
     configuration. Follow these steps to create a <em>rapdemo.warproduct</em>
     configuration for the RAP demo application:
   </p>
   <ul>
     <li>
       Open the <em class="UILabel">New WAR Product Configuration</em> wizard.<br/>
       <img src="../images/war_product_wizard.png" alt="WAR product wizard"/>
     </li>
     <li>
       Enter a name for the  war configuration file and select the
       <em>RAP Workbench Demo</em> from the available launch configurations.<br/>
       <img src="../images/war_product_configuration.png" alt="WAR product configuration"/>
     </li>
   </ul>

   <h3>The rapdemo.warproduct configuration</h3>
   <p>
     WAR Products tooling provides a form-based multi-page editor to manage a
     <em>.warproduct</em> configuration. The editor has the following pages:
   </p>
   <ul>
     <li>
       <em class="UILabel">Overview</em>: on this page you can enter additional information
       like <em>ID</em>, <em>Name</em>, <em>Version</em> but they are not
       needed to export a war archive. Also the <em class="UILabel">WAR Product export</em> wizard
       can be started from the <em class="UILabel">Overview page</em>.<br/>
       <img src="../images/war_product_editor.png" alt="WAR Product editor"/>
     </li>
     <li>
       <em class="UILabel">Configuration</em>: Here you can manage which plug-ins and libraries
       to be included into the war archive.<br/>
       <img src="../images/war_product_editor_configuration.png" alt="WAR Product editor configuration"/>
     </li>
     <li>
       <em class="UILabel">web.xml</em>: On this page the web.xml of the war archive can be edited.<br/>
       <img src="../images/war_product_editor_webxml.png" alt="WAR Product editor web.xml"/>
     </li>
   </ul>

   <h3>Create the WAR archive</h3>
   <p>
     From the <em class="UILabel">Overview</em> page of the <em>.warproduct</em> configuration
     editor start the <em class="UILabel">WAR Product export</em> wizard (this can also be reached by launching
     the general Export Wizard), enter the location for the war
     archive and press <em class="UILabel">Finish</em> if no validation errors exist. After that you can deploy
     the <em>WAR</em> file to a servlet container. See the uncommented sections in the <em>web.xml</em>
     for more information on how to activate the OSGi-console. This is useful if you run into troubles
     while deploying the generated WAR file.
   </p>

   <h2>How to deploy my own application?</h2>

   <p>
     To deploy your own application like described above you will have
     to create your own <em>.warproduct</em> configuration. The configuration
     should contain the same plug-in references as the <em>rapdemo.configuration</em>
     (except the demo-plug-in of course!) plus the plug-ins that make up your application.
     It is important that your plug-ins reference the Servlet API by using the
     <em>Import-Package</em> directive instead of the <em>Require-Bundle</em>
     directive. See the <em>MANIFEST.MF</em> of the demo project for an example.
   </p>

   <p>
     <strong>Note</strong>: Besides the application server log files
     there also exists an Equinox framework log that can be found under the webapp's
     work directory, e.g. on Tomcat:
   </p>
   <pre>
 &lt;tomcat-installation&gt;/work/Catalina/localhost/demo/eclipse/workspace/.metadata/.log </pre>

   <p>
   In case Equinox isn't able to start at all, you may also look for log files
   at:
   </p>
   <pre>
 &lt;tomcat-installation&gt;/work/Catalina/localhost/demo/eclipse/configuration </pre>

   <h2>Troubleshooting</h2>

   <p>
     You can use the following checklist to find errors when your exported application does not work:
   </p>

   <ul>
     <li>Check your <em>build.properties</em> file
       <ul>
         <li>Are you exporting the <em>plugin.xml</em>?</li>
         <li>If you are using <em>plugin.properties</em> files, make sure
           they are exported.</li>
         <li>Are all libraries you are using listed on the plug-ins class path?</li>
         <li>Tip: As PDE build sometimes swallows error messages try exporting
           your feature with <em>Deployable Feature</em> export, this may turn up
           error messages.</li>
       </ul>
     </li>
     <li>
       Enable the OSGi console by adding this init-param to the <em>web.xml</em>:
       <pre class="lang-xml">
 &lt;init-param&gt;
   &lt;param-name&gt;commandline&lt;/param-name&gt;
   &lt;param-value&gt;-console&lt;/param-value&gt;
 &lt;/init-param&gt;</pre>
       <ul>
         <li>You can add a port after <em>-console</em> and then telnet to
           the OSGi console: <br/><code>telnet localhost &lt;port&gt;</code>.</li>
         <li>Type <code>ss</code> in the console and see if all bundles are
           started. If not try starting them with
           <code>start &lt;bundle-id&gt;</code>.
           The stack traces may hint to what is missing.</li>
         <li>Make sure that there is a
         <em>org.eclipse.equinox.servletbridge.extensionbundle</em> in
         the <code>ss</code>-listing who's state is <code>RESOVLED</code>.</li>
       </ul>
     </li>
     <li>
       Make sure that the WAR does <b>not</b> contain the
       <em>javax.servlet</em> bundle.
       In the plug-in manifest the <em>javax.servlet</em> <b>must</b> be
       listed in the <em class="UILabel">Import-Package</em> section, not in
       <em class="UILabel">Require-Bundle</em>.</li>
     <li>
       Make sure that the WAR does <b>not</b> contain the
       <em>org.eclipse.update.configurator</em> bundle.</li>
     <li>
       Does the WAR contain compile errors?
       If so, you will probably find a zip archive somewhere in your output
       folder. It contains log files with the compiler output.</li>
     <li>
       Start with a working example:
       Download
       <a href="http://rap.eclipsesource.com/download/rapdemo.war"><em>rapdemo.war</em></a>
       and integrate your plug-ins.</li>
     <li>
       Use the product export to validate your feature:
       <ul>
         <li>
           Create a product configuration with an arbitrary
           name (<em>File &gt; New &gt; Other &gt; Product Configuration</em>).
         </li>
         <li>
           Select <q>The product configuration is based on <em>features</em></q>
           on the <em>Overview</em> page.</li>
         <li>
           Add your feature to the list of features on the <em>Dependencies</em> page.
         </li>
         <li>
           Press the <em>Validate</em> button in the top-left corner of the editor.
           Ignore complaints about missing <em>javax.servlet</em> packages.
           Be aware that unresolved optional dependencies aren't reported as errors.
         </li>
       </ul>
     </li>
     <li>
       If you are re-deploying, make sure to delete the work directory of your
       servlet engine (e.g.
       <code>&lt;tomcat_install&gt;/work/Catalina/localhost/&lt;webapp_name&gt;</code>
       in Tomcat).
     </li>
   </ul>

   <p>
     Further hints can be found in the <a href="http://wiki.eclipse.org/RAP/FAQ">RAP FAQ</a>
   </p>

 </body>
 </html>
	<?xml version="1.0" encoding="UTF-8" ?>
	<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
	"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
	<html xmlns="http://www.w3.org/1999/xhtml">
	<head>
	<meta name="copyright" content="Copyright (c) 2007, 2013 EclipseSource. This page is made available under license. For full details see the LEGAL in the documentation book that contains this page."/>
	<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
	<title>Deployment</title>
	<link rel="stylesheet" href="../../../PRODUCT_PLUGIN/book.css" type="text/css"/>
	</head>
	<body>

	<h1>Deploying a RAP Application to a Servlet Container</h1>

	<p>
	The following tutorial shows how to create a <em>WAR</em> file that contains the
	<em>org.eclipse.rap.demo</em> project as a RAP application.
	</p>

	<p>
	Note: As with RCP applications there are a wide variety of possible configurations.
	What's given in this tutorial is just one possibility.
	</p>

	<p>
	As prerequisites we assume that you:
	</p>
	<ul>
	<li>
	are familiar with the bundles- and build information section of the
	<a href="http://www.eclipse.org/equinox/server/http_in_container.php">
	Equinox in a Servlet Container</a> document.
	</li>
	<li>
	have installed the WAR Products tooling from this p2 repository
	<a href="http://download.eclipse.org/releases/juno/">http://download.eclipse.org/releases/juno/</a>
	into your IDE. This tooling is part of <a href="http://eclipse.org/libra/">Libra</a> and not
	part of RAP. Anyway it can be used to deploy RAP applications in a very comfortable way.
	</li>
	<li>
	have set a target platform that contains RAP.
	</li>
	</ul>

	<h3>Import org.eclipse.rap.demo into your workspace</h3>
	<ul>
	<li>
	Open the <em class="UILabel">Plug-ins</em> view.
	</li>
	<li>
	Select the <em>org.eclipse.rap.demo</em> plug-in and use the command
	<em class="UILabel">Import As</em> > <em class="UILabel">Source Project</em> from the context menu to import
	<em>org.eclipse.rap.demo</em> as a project in your workspace.
	</li>
	</ul>
	<img src="../images/import_rap_demo.png" alt="Import RAP demo project"/>

	<h3>Create a .warproduct configuration</h3>
	<p>
	Building a <em>WAR</em> file using the WAR Products tooling is centered around
	a <em>.warproduct</em> configuration. The <em>.warproduct</em> configuration is
	entirely managed by the WAR Products tooling to simplify war deployment. It's format
	is internal and is not intended to be read by tools other than the WAR Products tooling.
	To create a <em>.warproduct</em> configuration you can use a working launch
	configuration. Follow these steps to create a <em>rapdemo.warproduct</em>
	configuration for the RAP demo application:
	</p>
	<ul>
	<li>
	Open the <em class="UILabel">New WAR Product Configuration</em> wizard.<br/>
	<img src="../images/war_product_wizard.png" alt="WAR product wizard"/>
	</li>
	<li>
	Enter a name for the war configuration file and select the
	<em>RAP Workbench Demo</em> from the available launch configurations.<br/>
	<img src="../images/war_product_configuration.png" alt="WAR product configuration"/>
	</li>
	</ul>

	<h3>The rapdemo.warproduct configuration</h3>
	<p>
	WAR Products tooling provides a form-based multi-page editor to manage a
	<em>.warproduct</em> configuration. The editor has the following pages:
	</p>
	<ul>
	<li>
	<em class="UILabel">Overview</em>: on this page you can enter additional information
	like <em>ID</em>, <em>Name</em>, <em>Version</em> but they are not
	needed to export a war archive. Also the <em class="UILabel">WAR Product export</em> wizard
	can be started from the <em class="UILabel">Overview page</em>.<br/>
	<img src="../images/war_product_editor.png" alt="WAR Product editor"/>
	</li>
	<li>
	<em class="UILabel">Configuration</em>: Here you can manage which plug-ins and libraries
	to be included into the war archive.<br/>
	<img src="../images/war_product_editor_configuration.png" alt="WAR Product editor configuration"/>
	</li>
	<li>
	<em class="UILabel">web.xml</em>: On this page the web.xml of the war archive can be edited.<br/>
	<img src="../images/war_product_editor_webxml.png" alt="WAR Product editor web.xml"/>
	</li>
	</ul>

	<h3>Create the WAR archive</h3>
	<p>
	From the <em class="UILabel">Overview</em> page of the <em>.warproduct</em> configuration
	editor start the <em class="UILabel">WAR Product export</em> wizard (this can also be reached by launching
	the general Export Wizard), enter the location for the war
	archive and press <em class="UILabel">Finish</em> if no validation errors exist. After that you can deploy
	the <em>WAR</em> file to a servlet container. See the uncommented sections in the <em>web.xml</em>
	for more information on how to activate the OSGi-console. This is useful if you run into troubles
	while deploying the generated WAR file.
	</p>

	<h2>How to deploy my own application?</h2>

	<p>
	To deploy your own application like described above you will have
	to create your own <em>.warproduct</em> configuration. The configuration
	should contain the same plug-in references as the <em>rapdemo.configuration</em>
	(except the demo-plug-in of course!) plus the plug-ins that make up your application.
	It is important that your plug-ins reference the Servlet API by using the
	<em>Import-Package</em> directive instead of the <em>Require-Bundle</em>
	directive. See the <em>MANIFEST.MF</em> of the demo project for an example.
	</p>

	<p>
	<strong>Note</strong>: Besides the application server log files
	there also exists an Equinox framework log that can be found under the webapp's
	work directory, e.g. on Tomcat:
	</p>
	<pre>
	<tomcat-installation>/work/Catalina/localhost/demo/eclipse/workspace/.metadata/.log </pre>

	<p>
	In case Equinox isn't able to start at all, you may also look for log files
	at:
	</p>
	<pre>
	<tomcat-installation>/work/Catalina/localhost/demo/eclipse/configuration </pre>

	<h2>Troubleshooting</h2>

	<p>
	You can use the following checklist to find errors when your exported application does not work:
	</p>

	<ul>
	<li>Check your <em>build.properties</em> file
	<ul>
	<li>Are you exporting the <em>plugin.xml</em>?</li>
	<li>If you are using <em>plugin.properties</em> files, make sure
	they are exported.</li>
	<li>Are all libraries you are using listed on the plug-ins class path?</li>
	<li>Tip: As PDE build sometimes swallows error messages try exporting
	your feature with <em>Deployable Feature</em> export, this may turn up
	error messages.</li>
	</ul>
	</li>
	<li>
	Enable the OSGi console by adding this init-param to the <em>web.xml</em>:
	<pre class="lang-xml">
	<init-param>
	<param-name>commandline</param-name>
	<param-value>-console</param-value>
	</init-param></pre>
	<ul>
	<li>You can add a port after <em>-console</em> and then telnet to
	the OSGi console: <br/><code>telnet localhost <port></code>.</li>
	<li>Type <code>ss</code> in the console and see if all bundles are
	started. If not try starting them with
	<code>start <bundle-id></code>.
	The stack traces may hint to what is missing.</li>
	<li>Make sure that there is a
	<em>org.eclipse.equinox.servletbridge.extensionbundle</em> in
	the <code>ss</code>-listing who's state is <code>RESOVLED</code>.</li>
	</ul>
	</li>
	<li>
	Make sure that the WAR does <b>not</b> contain the
	<em>javax.servlet</em> bundle.
	In the plug-in manifest the <em>javax.servlet</em> <b>must</b> be
	listed in the <em class="UILabel">Import-Package</em> section, not in
	<em class="UILabel">Require-Bundle</em>.</li>
	<li>
	Make sure that the WAR does <b>not</b> contain the
	<em>org.eclipse.update.configurator</em> bundle.</li>
	<li>
	Does the WAR contain compile errors?
	If so, you will probably find a zip archive somewhere in your output
	folder. It contains log files with the compiler output.</li>
	<li>
	Start with a working example:
	Download
	<a href="http://rap.eclipsesource.com/download/rapdemo.war"><em>rapdemo.war</em></a>
	and integrate your plug-ins.</li>
	<li>
	Use the product export to validate your feature:
	<ul>
	<li>
	Create a product configuration with an arbitrary
	name (<em>File > New > Other > Product Configuration</em>).
	</li>
	<li>
	Select <q>The product configuration is based on <em>features</em></q>
	on the <em>Overview</em> page.</li>
	<li>
	Add your feature to the list of features on the <em>Dependencies</em> page.
	</li>
	<li>
	Press the <em>Validate</em> button in the top-left corner of the editor.
	Ignore complaints about missing <em>javax.servlet</em> packages.
	Be aware that unresolved optional dependencies aren't reported as errors.
	</li>
	</ul>
	</li>
	<li>
	If you are re-deploying, make sure to delete the work directory of your
	servlet engine (e.g.
	<code><tomcat_install>/work/Catalina/localhost/<webapp_name></code>
	in Tomcat).
	</li>
	</ul>

	<p>
	Further hints can be found in the <a href="http://wiki.eclipse.org/RAP/FAQ">RAP FAQ</a>
	</p>

	</body>
	</html>