Difference between revisions of "Gemini/Web"

From Eclipsepedia

Jump to: navigation, search
(Trying out Gemini Web)
(Set as a Target Platform in PDE)
 
(40 intermediate revisions by 3 users not shown)
Line 3: Line 3:
 
Gemini Web is a sister project of Virgo. Please refer to the [[Virgo|Virgo wiki]] for salient information.
 
Gemini Web is a sister project of Virgo. Please refer to the [[Virgo|Virgo wiki]] for salient information.
  
= Trying out Gemini Web  =
+
== Trying out Gemini Web  ==
  
1. [http://download.eclipse.org/equinox/ Download] the Equinox JAR, for example org.eclipse.osgi_3.6.0.v20100517.jar, and move it to a suitable directory (e.g. ~/gemini-web-test).  
+
1. [http://download.eclipse.org/equinox/ Download] the Equinox JAR, and move it to a suitable directory (e.g. ~/gemini-web-test). On the [http://download.eclipse.org/equinox/ Download] page first choose the Release for the appropriate Gemini Web version, then download the JAR from the ''Framework'' section.
 +
  a. Gemini Web 1.1.x - for example [http://download.eclipse.org/equinox/drops/R-3.6-201006080911/download.php?dropFile=org.eclipse.osgi_3.6.0.v20100517.jar org.eclipse.osgi_3.6.0.v20100517.jar]
 +
  b. Gemini Web 2.0.x, 2.1.x - for example [http://download.eclipse.org/equinox/drops/R-3.7.1-201109091335/download.php?dropFile=org.eclipse.osgi_3.7.1.R37x_v20110808-1106.jar org.eclipse.osgi_3.7.1.R37x_v20110808-1106.jar]
  
2. [http://www.eclipse.org/gemini/web/download Download] Gemini Web and unzip it to ~/gemini-web-test/gemini-web.  
+
2. [http://www.eclipse.org/gemini/web/download Download] Gemini Web and unzip it to ~/gemini-web-test/gemini-web.  
  
3. Configure Equinox by creating a directory ~/gemini-web-test/configuration and create a config.ini file in the configuration directory. An example which works with 1.1.0.M01 is available (in zipped form) [http://wiki.eclipse.org/images/5/5e/Config.ini.zip here]. Essentially this file ensures that the dependencies of Gemini Web, which come in the dep directory, are installed and then the Gemini Web bundles are installed and started.  
+
3. Configure Equinox by creating a directory ~/gemini-web-test/configuration
 +
  a. Gemini Web 1.1.x - Create files config.ini and Java6-server.profile in the configuration directory. Example files which works with '''1.1.0.RELEASE'''
 +
      are available in [http://wiki.eclipse.org/images/5/5e/Config.ini.zip config.ini.zip] and [http://wiki.eclipse.org/images/3/32/Java6-server.profile.zip Java6-server.profile.zip].
 +
  b. Gemini Web 2.0.x - Create file config.ini in the configuration directory. Example file which works with '''2.0.1.RELEASE''' is available in [http://wiki.eclipse.org/images/0/0b/Config.ini.2.0.1.zip config.ini.zip].
 +
  c. Gemini Web 2.1.x - Create file config.ini in the configuration directory. Example file which works with '''2.1.0.RELEASE''' is available in [http://wiki.eclipse.org/images/2/23/Config.ini.2.1.0.zip config.ini.zip].
 +
Essentially config.ini ensures that Java6-server.profile is used and that the dependencies of Gemini Web, which come in the dep directory, are installed and then the Gemini Web bundles are installed and started. Java6-server.profile ensures that javax.xml.ws is exported at version 2.1.1 from the system bundle as the Tomcat bundles in Gemini Web depend on that version.  
  
 
4. Start Equinox as follows:  
 
4. Start Equinox as follows:  
<pre> java -jar org.eclipse.osgi_3.6.0.v20100517.jar -console
+
  a. Gemini Web 1.1.x
</pre>
+
      java -jar org.eclipse.osgi_3.6.0.v20100517.jar -console
5. You can then install WAR files and web bundles using the install command from the console. Refer to the [http://www.eclipse.org/gemini/web/documentation documentation] for more information.  
+
  b. Gemini Web 2.0.x, 2.1.x
 +
      java -jar org.eclipse.osgi_3.7.1.R37x_v20110808-1106.jar -console
 +
 
 +
5. You can then deploy WAR files (a trivial example is available in [http://wiki.eclipse.org/images/f/f6/Osgi.web.app.zip Osgi.web.app.zip]) and web bundles using the install and start commands from the console. Refer to the [http://www.eclipse.org/gemini/web/documentation documentation] for more information.
 +
<pre>osgi&gt; install file:osgi.web.app.war
 +
Bundle id is 42
 +
osgi&gt; start 42
 +
</pre>
 +
6. Drive the WAR or web bundle using a web browser, e.g. [http://localhost:8080/osgi-web-app http://localhost:8080/osgi-web-app].
 +
 
 +
== Set as a Target Platform in PDE ==
 +
 
 +
The following steps enable you to develop Web Application Bundles that compile against the libraries of the Gemini Web container by using the existing [http://eclipse.org/pde/ Plug-in Development Environment (PDE)] tooling in Eclipse.
 +
 
 +
[[Image:Equinox-update-site.png|thumb|Target Platform for Eclipse Gemini Web, setup Equinox Core Function, 8.3-8.5]]
 +
 
 +
# Open ''Window > Preferences'' from the main menu in the Eclipse IDE.
 +
# Navigate to the ''Plug-in Development > Target Platform'' preferences page.
 +
# Click the ''Add...'' button.
 +
# Choose ''Nothing: start with an empty target definition'' and click ''Next >''
 +
# Give a ''Name'' for the new target definition (like "Gemini Web").
 +
# Make sure the ''Locations'' tab is the active one and click the ''Add...'' button.
 +
# Gemini Web 1.1.x
 +
## Choose ''Directory'' and press the ''Next >'' button.
 +
## Browse to the ~/gemini-web-test folder and click the ''Finish'' button.
 +
## Repeat steps 7.1-7.3 to add the ~/gemini-web-test/gemini-web and ~/gemini-web-test/gemini-web/dep folders to the target definition.
 +
# Gemini Web 2.0.x, 2.1.x
 +
## Choose ''Software Site'' and press the ''Next >'' button.
 +
## In ''Work with:'' field paste Eclipse update site link ''http://download.eclipse.org/eclipse/updates/3.7/''.
 +
## In the filter field, type ''equinox''.
 +
## Make sure that the option ''Group by Category'' is unchecked.
 +
## From the list with available items, choose ''Equinox Core Function''. Click the ''Finish'' button.
 +
## Click on the ''Content'' tab, deselect all bundles and then select only ''org.eclipse.osgi''.
 +
## Make sure the ''Locations'' tab is the active again and click the ''Add...'' button.
 +
## Choose ''Software Site'' and press the ''Next >'' button.
 +
## In ''Work with:'' field paste Gemini Web update site link
 +
### Gemini Web 2.0.x - ''http://download.eclipse.org/gemini/updates/web/2.0.1/''.
 +
### Gemini Web 2.1.x - ''http://download.eclipse.org/gemini/updates/web/2.1.0/''.
 +
## Make sure that this time the option ''Group by Category'' is checked.
 +
## From the list with available items, choose ''Eclipse Gemini Web''. Click the ''Finish'' button.
 +
## Make sure that all 42 bundles from that update site are selected.
 +
# Click the ''Finish'' button to close the ''New Target Definition'' wizard.
 +
# Select the newly created target definition and click the ''OK'' button to activate it for you PDE environment.
 +
 
 +
== Run as OSGi Framework from the Eclipse IDE ==
 +
 
 +
The following steps enable you to deploy and run the Web Application Bundles in your Eclipse workspace on the Gemini Web container.
 +
 
 +
[[Image:Gemini_Web_OSGi_Framework.png|thumb|OSGi Framework run configuration, Bundles tab]]
 +
[[Image:Gemini_Web_OSGi_Framework_Arguments.png|thumb|OSGi Framework run configuration, Arguments tab]]
 +
[[Image:Gemini_Web_OSGi_Framework_Settings.png|thumb|OSGi Framework run configuration, Settings tab]]
 +
 
 +
# Make sure you have set the Gemini Web container as a target platform as described in the previous section.
 +
# Open ''Run > Run Configurations...'' from the main menu of the Eclipse IDE.
 +
# Navigate to the ''OSGi Framework'' category.
 +
# ''Right-click > New''.
 +
# Give a ''Name'' for you run configuration (like "Gemini Web").
 +
# Open the ''Bundles'' tab.
 +
# Make sure all of the bundles under the ''Target Platform'' node are selected.
 +
# Select the bundles from the ''Workspace'' you want to deploy in the Gemini Web container.
 +
# Gemini Web 1.1.x
 +
## Switch to the ''Arguments'' tab.
 +
## Add the following system property to the ''VM arguments'': '''-Dosgi.java.profile=file:configuration/java6-server.profile'''
 +
## Select the ''Other'' radio button in the ''Working directory'' group and specify the path to the ~/gemini-web-test folder.
 +
## Switch to the ''Settings'' tab.
 +
## Deselect the ''Use default location'' check box in the ''Configuration Area'' group.
 +
## Specify the path to the ~/gemini-web-test/configuration folder in the ''Location'' text field.
 +
# Gemini Web 2.0.x - no additional changes needed.
 +
# Click the ''Run'' button.
 +
 
 +
You will see some logs dumped in the ''Console'' view. After a second the Gemini Web container is started and the Web Application Bundles from the workspace are deployed. You can now call you application from the browser using URLs like:
 +
 
 +
<nowiki>http://localhost:8080/<context-root>/...</nowiki>
 +
 
 +
The above steps are needed only for the first run of Gemini Web. Any subsequent runs can be executed much simpler:
 +
* Right-click your Web Application Bundle project and call ''Run As > OSGi Framework''. That's all.
 +
 
 +
== How to stop Gemini Web? ==
 +
 
 +
The safest way to stop Gemini Web is to type <code>close</code> in the ''Console'' view and hit '''Enter'''.
 +
 
 +
You need to stop any old instance of Gemini Web before starting it again. Otherwise, the new instance won't start correctly, because the old one still occupies the http port (and, perhaps, other system resources).
 +
 
 +
== How to run in debug mode? ==
 +
 
 +
Running in debug mode is done simply by:
 +
* Right-click your Web Application Bundle project and call ''Debug As > OSGi Framework''. That's all.
 +
 
 +
You will get all debug features (including hot code replace) from JDT and PDE for free.
 +
 
 +
== Limitations ==
 +
 
 +
Gemini Web is a designed to be an application server component rather than a fully-functional application server. As such it has some limitations:
 +
 
 +
* Some resources are not available by URL (see [https://bugs.eclipse.org/bugs/show_bug.cgi?id=325578 bug 325578]). Virgo, for example, works around this by installing an Equinox hook to ensure that all resource URLs returned have a "file:" protocol and not a "bundleresource:" protocol which is the default returned by Equinox.
  
 
[[Category:Gemini_Web|Web]]
 
[[Category:Gemini_Web|Web]]

Latest revision as of 05:00, 21 July 2012

Gemini Web is a subproject of the Gemini project.

Gemini Web is a sister project of Virgo. Please refer to the Virgo wiki for salient information.

Contents

[edit] Trying out Gemini Web

1. Download the Equinox JAR, and move it to a suitable directory (e.g. ~/gemini-web-test). On the Download page first choose the Release for the appropriate Gemini Web version, then download the JAR from the Framework section.

  a. Gemini Web 1.1.x - for example org.eclipse.osgi_3.6.0.v20100517.jar
  b. Gemini Web 2.0.x, 2.1.x - for example org.eclipse.osgi_3.7.1.R37x_v20110808-1106.jar

2. Download Gemini Web and unzip it to ~/gemini-web-test/gemini-web.

3. Configure Equinox by creating a directory ~/gemini-web-test/configuration

  a. Gemini Web 1.1.x - Create files config.ini and Java6-server.profile in the configuration directory. Example files which works with 1.1.0.RELEASE 
     are available in config.ini.zip and Java6-server.profile.zip. 
  b. Gemini Web 2.0.x - Create file config.ini in the configuration directory. Example file which works with 2.0.1.RELEASE is available in config.ini.zip.
  c. Gemini Web 2.1.x - Create file config.ini in the configuration directory. Example file which works with 2.1.0.RELEASE is available in config.ini.zip.

Essentially config.ini ensures that Java6-server.profile is used and that the dependencies of Gemini Web, which come in the dep directory, are installed and then the Gemini Web bundles are installed and started. Java6-server.profile ensures that javax.xml.ws is exported at version 2.1.1 from the system bundle as the Tomcat bundles in Gemini Web depend on that version.

4. Start Equinox as follows:

  a. Gemini Web 1.1.x
     java -jar org.eclipse.osgi_3.6.0.v20100517.jar -console
  b. Gemini Web 2.0.x, 2.1.x
     java -jar org.eclipse.osgi_3.7.1.R37x_v20110808-1106.jar -console

5. You can then deploy WAR files (a trivial example is available in Osgi.web.app.zip) and web bundles using the install and start commands from the console. Refer to the documentation for more information.

osgi> install file:osgi.web.app.war
Bundle id is 42
osgi> start 42 

6. Drive the WAR or web bundle using a web browser, e.g. http://localhost:8080/osgi-web-app.

[edit] Set as a Target Platform in PDE

The following steps enable you to develop Web Application Bundles that compile against the libraries of the Gemini Web container by using the existing Plug-in Development Environment (PDE) tooling in Eclipse.

Target Platform for Eclipse Gemini Web, setup Equinox Core Function, 8.3-8.5
  1. Open Window > Preferences from the main menu in the Eclipse IDE.
  2. Navigate to the Plug-in Development > Target Platform preferences page.
  3. Click the Add... button.
  4. Choose Nothing: start with an empty target definition and click Next >
  5. Give a Name for the new target definition (like "Gemini Web").
  6. Make sure the Locations tab is the active one and click the Add... button.
  7. Gemini Web 1.1.x
    1. Choose Directory and press the Next > button.
    2. Browse to the ~/gemini-web-test folder and click the Finish button.
    3. Repeat steps 7.1-7.3 to add the ~/gemini-web-test/gemini-web and ~/gemini-web-test/gemini-web/dep folders to the target definition.
  8. Gemini Web 2.0.x, 2.1.x
    1. Choose Software Site and press the Next > button.
    2. In Work with: field paste Eclipse update site link http://download.eclipse.org/eclipse/updates/3.7/.
    3. In the filter field, type equinox.
    4. Make sure that the option Group by Category is unchecked.
    5. From the list with available items, choose Equinox Core Function. Click the Finish button.
    6. Click on the Content tab, deselect all bundles and then select only org.eclipse.osgi.
    7. Make sure the Locations tab is the active again and click the Add... button.
    8. Choose Software Site and press the Next > button.
    9. In Work with: field paste Gemini Web update site link
      1. Gemini Web 2.0.x - http://download.eclipse.org/gemini/updates/web/2.0.1/.
      2. Gemini Web 2.1.x - http://download.eclipse.org/gemini/updates/web/2.1.0/.
    10. Make sure that this time the option Group by Category is checked.
    11. From the list with available items, choose Eclipse Gemini Web. Click the Finish button.
    12. Make sure that all 42 bundles from that update site are selected.
  9. Click the Finish button to close the New Target Definition wizard.
  10. Select the newly created target definition and click the OK button to activate it for you PDE environment.

[edit] Run as OSGi Framework from the Eclipse IDE

The following steps enable you to deploy and run the Web Application Bundles in your Eclipse workspace on the Gemini Web container.

OSGi Framework run configuration, Bundles tab
OSGi Framework run configuration, Arguments tab
OSGi Framework run configuration, Settings tab
  1. Make sure you have set the Gemini Web container as a target platform as described in the previous section.
  2. Open Run > Run Configurations... from the main menu of the Eclipse IDE.
  3. Navigate to the OSGi Framework category.
  4. Right-click > New.
  5. Give a Name for you run configuration (like "Gemini Web").
  6. Open the Bundles tab.
  7. Make sure all of the bundles under the Target Platform node are selected.
  8. Select the bundles from the Workspace you want to deploy in the Gemini Web container.
  9. Gemini Web 1.1.x
    1. Switch to the Arguments tab.
    2. Add the following system property to the VM arguments: -Dosgi.java.profile=file:configuration/java6-server.profile
    3. Select the Other radio button in the Working directory group and specify the path to the ~/gemini-web-test folder.
    4. Switch to the Settings tab.
    5. Deselect the Use default location check box in the Configuration Area group.
    6. Specify the path to the ~/gemini-web-test/configuration folder in the Location text field.
  10. Gemini Web 2.0.x - no additional changes needed.
  11. Click the Run button.

You will see some logs dumped in the Console view. After a second the Gemini Web container is started and the Web Application Bundles from the workspace are deployed. You can now call you application from the browser using URLs like:

http://localhost:8080/<context-root>/...

The above steps are needed only for the first run of Gemini Web. Any subsequent runs can be executed much simpler:

  • Right-click your Web Application Bundle project and call Run As > OSGi Framework. That's all.

[edit] How to stop Gemini Web?

The safest way to stop Gemini Web is to type close in the Console view and hit Enter.

You need to stop any old instance of Gemini Web before starting it again. Otherwise, the new instance won't start correctly, because the old one still occupies the http port (and, perhaps, other system resources).

[edit] How to run in debug mode?

Running in debug mode is done simply by:

  • Right-click your Web Application Bundle project and call Debug As > OSGi Framework. That's all.

You will get all debug features (including hot code replace) from JDT and PDE for free.

[edit] Limitations

Gemini Web is a designed to be an application server component rather than a fully-functional application server. As such it has some limitations:

  • Some resources are not available by URL (see bug 325578). Virgo, for example, works around this by installing an Equinox hook to ensure that all resource URLs returned have a "file:" protocol and not a "bundleresource:" protocol which is the default returned by Equinox.