Difference between revisions of "Virgo/FAQ"

From Eclipsepedia

Jump to: navigation, search
(How can I change the version of Spring framework in the user region?)
(43 intermediate revisions by 7 users not shown)
Line 1: Line 1:
 
{{Virgo}}
 
{{Virgo}}
 
[[Category:Virgo]] [[Category:EclipseRT]]
 
[[Category:Virgo]] [[Category:EclipseRT]]
 +
= How can I get help fast? =
 +
 +
'''Stop!'''  Unless you have taken out a commercial support agreement with a suitable provider, you'll need to ''take the lead'' in solving your problem.
 +
 +
The [http://www.eclipse.org/forums/index.php?t=thread&frm_id=159 Virgo forum] is there for you to discuss your problem with others, who may then be able to give you some hints to help you take the next step.
 +
 +
But before you rush in and post your application saying "It doesn't work. Please help!" or claiming that your schedule is tight and "this is an emergency", please read ''the whole of'' [http://catb.org/~esr/faqs/smart-questions.html How to Ask Questions the Smart Way] (but note that page is not a "help desk" for Virgo) and you'll be ''much'' more likely to get the help you need — fast.
  
 
= How can I diagnose class loading problems? =
 
= How can I diagnose class loading problems? =
  
See this [http://hsiliev.blogspot.com/2010/12/troubleshooting-class-loading-issues-in.html blog].
+
Use the [http://eclipse.org/virgo/documentation/virgo-documentation-3.6.0.RELEASE/docs/virgo-user-guide/html/ch08s02.html Virgo Shell Commands] as described in this [http://hsiliev.blogspot.com/2010/12/troubleshooting-class-loading-issues-in.html blog].
  
 
= What's a uses constraint and what can I do if one is violated? =
 
= What's a uses constraint and what can I do if one is violated? =
Line 19: Line 26:
  
 
See this [http://underlap.blogspot.com/2011/02/thread-context-class-loading-in-virgo.html blog].
 
See this [http://underlap.blogspot.com/2011/02/thread-context-class-loading-in-virgo.html blog].
 +
 +
= Are Virgo bundles published to a Maven Repo anywhere. =
 +
 +
Yes, they are available over http from http://build.eclipse.org/rt/virgo/maven/bundles/
  
 
= How can I get a graphical application to work in Virgo? =
 
= How can I get a graphical application to work in Virgo? =
  
To get GUI apps to work in Virgo, you have to edit lib/java6-server.profile in order to add some packages to the org.osgi.framework.bootdelegation property.
+
To get GUI apps to work in Virgo, you have to edit <tt>lib/java6-server.profile</tt> in order to add some packages to the <tt>org.osgi.framework.bootdelegation</tt> property.
  
 
On Mac, you need to add some Apple packages:
 
On Mac, you need to add some Apple packages:
Line 39: Line 50:
 
   com.apple.*</span>
 
   com.apple.*</span>
  
On Windows, you just need to add com.sun.* as sun.* is already in the list.
+
On Windows, you just need to add <tt>com.sun.*</tt> as <tt>sun.*</tt> is already in the list.
  
 
  org.osgi.framework.bootdelegation = \
 
  org.osgi.framework.bootdelegation = \
Line 53: Line 64:
 
   com.sun.*</span>
 
   com.sun.*</span>
  
= How can I change the version of Spring framework in the user region? =
+
= How can I change the version of Spring framework in the user region? =
  
You can upgrade or downgrade the version of Spring framework in the user region provided the new version satisfies the version range required by Virgo. Virgo 3.0.x can use 3.0.x versions of Spring framework.
+
You can upgrade or downgrade the version of Spring framework in the user region provided the new version satisfies the version range required by Virgo. Virgo 3.0.x can use 3.0.x versions of Spring framework. To use Spring framework 3.1.x requires Virgo 3.5.0 or later. To use Spring framework 3.2.x requires Virgo 3.6.0 or later.  
  
To upgrade or downgrade, delete the Spring framework bundles and .libd file in repository/ext and then add the corresponding bundles and .libd file for the replacement version of Spring framework. The Spring framework bundles are listed in the .libd file if you are uncertain about which they are. Then re-start Virgo with the -clean switch and the user region should now run with the replacement version of Spring framework.
+
To upgrade or downgrade, delete the Spring framework bundles and <tt>.libd</tt> file in <tt>repository/ext</tt> and then add the corresponding bundles and <tt>.libd</tt> file for the replacement version of Spring framework. The Spring framework bundles are listed in the <tt>.libd</tt> file if you are uncertain about which they are. Then re-start Virgo with the <tt>-clean</tt> switch and the user region should now run with the replacement version of Spring framework.  
  
Here's an example of upgrading Spring framework on a UNIX system:
+
Here's an example of upgrading Spring framework on a UNIX system:  
  
 
  cd repository/ext/
 
  cd repository/ext/
Line 65: Line 76:
 
  cp /.../spring-framework-3.0.6/dist/org.springframework.* .
 
  cp /.../spring-framework-3.0.6/dist/org.springframework.* .
  
Note that it is not necessary to change the version of Spring framework used by the Virgo kernel as that version is independent of the version of Spring framework used by the user region.
+
Note that it is not necessary to change the version of Spring framework used by the Virgo kernel as that version is independent of the version of Spring framework used by the user region.  
  
If you want to use Spring framework version less than 3.0 (for instance 2.5.6.SEC2) you will have to use Virgo 2.1.x or Virgo Jetty Server 3.0. The reason for this is that Virgo Tomcat Server 3.0.x ships with Tomcat 7 and Servlet 3.0, while Spring framework 2.5.6 import range allows maximum Servlet 2.5 and this makes the two incompatible.
+
If you want to use Spring framework 3.2.1 or later on Virgo 3.6.x, you need to upgrade AspectJ to 1.7.1 as follows:
 +
 
 +
*Copy com.springsource.org.aspectj.weaver-1.7.1.RELEASE.jar to:
 +
**repository/ext
 +
**plugins
 +
 
 +
*Update configuration/org.eclipse.virgo.kernel.userregion.properties by changing the AspectJ line to this:
 +
 
 +
  org.aspectj.*;version="[1.7.1.RELEASE,2.0.0)",\
 +
 
 +
*Update configuration/org.eclipse.equinox.simpleconfigurator/bundles.info by changing the AspectJ line to this:
 +
 
 +
  com.springsource.org.aspectj.weaver,1.7.1.RELEASE,plugins/com.springsource.org.aspectj.weaver-1.7.1.RELEASE.jar,4,false
 +
 
 +
If you want to use a Spring framework version less than 3.1, you will have to use Virgo 2.1.x, 3.0.x, or 3.5.x. Virgo 3.6.x requires Spring framework 3.1 or later (see [https://bugs.eclipse.org/bugs/show_bug.cgi?id=398393 bug 398393]).
 +
 
 +
If you want to use a Spring framework version less than 3.0 (for instance 2.5.6.SEC2) you will have to use Virgo 2.1.x or Virgo Jetty Server 3.0. The reason for this is that Virgo Server for Apache Tomcat 3.0.x ships with Tomcat 7 and Servlet 3.0, while Spring framework 2.5.6 import range allows maximum Servlet 2.5 and this makes the two incompatible.
  
 
= How can I programmatically deploy applications to Virgo?  =
 
= How can I programmatically deploy applications to Virgo?  =
Line 73: Line 100:
 
This can be achieved using the MBeans registered by Virgo. It's best to explore them first using something like JConsole. The [http://virgo-opengrok.springsource.org/xref/virgo/org.eclipse.virgo.kernel/org.eclipse.virgo.kernel.deployer/src/main/java/org/eclipse/virgo/kernel/deployer/Deployer.java deployer] MBean can be used to specify an artifact with a URI that should be deployed (installed and started). Prefixes "file:" and "repository:" can be used. In the case of repository a URL of the form "repository://type/name[/version]" will refer to an artifact in a provisioning repository. The square brackets indicate that the trailing "/version" is optional, in which case Virgo uses the highest version available, and are not part of the URL. In the case of a bundle, "type" is "bundle" and "name" is the bundle symbolic name (and if "version" is specified, it is the bundle version).  
 
This can be achieved using the MBeans registered by Virgo. It's best to explore them first using something like JConsole. The [http://virgo-opengrok.springsource.org/xref/virgo/org.eclipse.virgo.kernel/org.eclipse.virgo.kernel.deployer/src/main/java/org/eclipse/virgo/kernel/deployer/Deployer.java deployer] MBean can be used to specify an artifact with a URI that should be deployed (installed and started). Prefixes "file:" and "repository:" can be used. In the case of repository a URL of the form "repository://type/name[/version]" will refer to an artifact in a provisioning repository. The square brackets indicate that the trailing "/version" is optional, in which case Virgo uses the highest version available, and are not part of the URL. In the case of a bundle, "type" is "bundle" and "name" is the bundle symbolic name (and if "version" is specified, it is the bundle version).  
  
Note that you ''can'' also install bundles using BundleContext.installBundle and they will be installed in the same region as the bundle whose BundleContext used to perform the install. However, bundles installed in this way will ''not'' pass through the Virgo deployment pipeline and will ''not'' be subject to the transformations normally applied to bundles as they are deployed in Virgo.
+
Note that you ''can'' also install bundles using <tt>BundleContext.installBundle</tt> and they will be installed in the same region as the bundle whose bundle context was used to perform the install. However, bundles installed in this way will ''not'' pass through the Virgo deployment pipeline and will ''not'' be subject to the transformations normally applied to bundles as they are deployed in Virgo.
 +
 
 +
= My Web Application Bundle stopped working when I moved to Virgo 3.x. What happened? =
 +
 
 +
Virgo Server for Apache Tomcat 3.0 conforms more strictly to the OSGi web applications specification and does not apply default values to some of the manifest headers of a WAB like it used to in Virgo 2.x.
 +
 
 +
You can easily check whether this is the problem as follows.
 +
 
 +
As a migration aid, which may be removed in future releases, the previous behaviour may be re-instated by [http://www.eclipse.org/virgo/documentation/virgo-documentation-3.0.0.RELEASE/docs/virgo-user-guide/html/ch11s08.html configuring] the Web Integration Layer to set WABHeaders=defaulted in $SERVER_HOME/repository/ext/org.eclipse.virgo.web.properties. Please note there is a [http://www.eclipse.org/virgo/documentation/virgo-documentation-3.0.0.RELEASE/docs/virgo-user-guide/html/apbs07.html known issue] with certain WAR files which may be worked around using this migration aid.
 +
 
 +
= Should I put Spring XML files in <tt>META-INF/spring</tt> or <tt>WEB-INF</tt>? =
 +
 
 +
You should put Spring application context XML configuration files in the <tt>WEB-INF</tt> directory of a web application bundle and in the <tt>META-INF/spring</tt> directory of a non-web bundle.
 +
 
 +
Putting these files in the <tt>META-INF/spring</tt> directory of a web application bundle is a common mistake and produces unpredictable results since Spring DM will attempt to build an application context independently of, and asynchronously from, the web application.
 +
 
 +
= Why is there both a config and a configuration directory? =
 +
 
 +
The <tt>config</tt> directory has always contained Virgo configuration files. When Virgo Nano and its support for p2 provisioning was introduced in Virgo 3.5.0, a <tt>configuration</tt> directory was added (see [https://bugs.eclipse.org/bugs/show_bug.cgi?id=324991 bug 324991] for details). The directory name <tt>configuration</tt> in the install's root is used by default in p2.
 +
 
 +
The Configuration chapter of the Virgo User Guide makes it clear which configuration goes in each directory.
 +
 
 +
= Why is my required bundle with version x.y.z. not resolved? =
 +
 
 +
To specify a version in a Require-Bundle header an (OSGi standard) attribute '''bundle-version''' is needed.
 +
 
 +
<code>
 +
Require-Bundle: bar;bundle-version="[x.y.z,x.y.z]"
 +
</code>
 +
 
 +
The attribute is spelled '''bundle-version=''' rather than '''version=''' as used with Import-Package. A misspelled attribute can show the following error:
 +
 
 +
<code>
 +
    Resolver report:
 +
        A Require-Bundle could not be resolved. Caused by missing constraint in bundle <foo_1.0.0>
 +
            constraint: <Require-Bundle: bar; bundle-version="0.0.0">
 +
</code>
 +
 
 +
If a required bundle cannot be resolved check the spelling of the attribute as well as the location of the required bundle.
 +
 
 +
= What's the difference between Virgo Server for Apache Tomcat and Virgo Jetty Server? =
 +
 
 +
*Virgo Server for Apache Tomcat (VTS) is based on embedded Tomcat, so its configuration and behaviour is familiar to Tomcat users. Virgo Jetty Server (VJS) is based on Jetty, so its configuration and behaviour is familiar to Jetty users.
 +
 
 +
* Please refer to the official [http://tomcat.apache.org/ Tomcat] and [http://www.eclipse.org/jetty/ Jetty] sites for details of these projects.
 +
 
 +
* Both VTS and VJS support standard OSGi Web Application Bundles, but only VTS supports WAR files (see [https://bugs.eclipse.org/bugs/show_bug.cgi?id=336955 bug 336955]).
 +
 
 +
* VTS supports the hosted repository application and can act as a Virgo repository server, but VJS cannot.
 +
 
 +
* VTS embeds Gemini Web which in turn embeds (embedded) Tomcat; VJS embeds Jetty.
 +
 
 +
* Virgo Snaps supports VTS but not VJS.
 +
 
 +
* VJS has known problems with TagLibs (see [https://bugs.eclipse.org/bugs/show_bug.cgi?id=349010 bug 349010]).
 +
 
 +
= What's the difference between Virgo Server for Apache Tomcat and Virgo Nano Web? =
 +
 
 +
See the [http://www.eclipse.org/virgo/feature-summary/ feature comparison summary].
 +
 
 +
= What's the difference between Virgo Server for Apache Tomcat and Virgo Tomcat Server? =
 +
 
 +
None. We renamed Virgo Tomcat Server to Virgo Server for Apache Tomcat to conform to [http://tomcat.apache.org/legal.html Tomcat legal requirements].
 +
 
 +
= What version of the Servlet Specification is supported by Virgo? =
 +
 
 +
* Virgo Server for Apache Tomcat version 2.x uses embedded Apache Tomcat 6.0.y which supports Servlet Specification 2.5.
 +
 
 +
* Virgo Server for Apache Tomcat version 3.x uses embedded Apache Tomcat 7.0.y which supports Servlet Specification 3.0.
 +
 
 +
* Virgo Jetty Server version 3.0.x uses Jetty 7.y. which supports Servlet Specification 2.5.
 +
 
 +
* Virgo Jetty Server version 3.5.x uses Jetty 8.y which supports Servlet Specification 3.0.

Revision as of 05:28, 13 February 2013

Contents

How can I get help fast?

Stop! Unless you have taken out a commercial support agreement with a suitable provider, you'll need to take the lead in solving your problem.

The Virgo forum is there for you to discuss your problem with others, who may then be able to give you some hints to help you take the next step.

But before you rush in and post your application saying "It doesn't work. Please help!" or claiming that your schedule is tight and "this is an emergency", please read the whole of How to Ask Questions the Smart Way (but note that page is not a "help desk" for Virgo) and you'll be much more likely to get the help you need — fast.

How can I diagnose class loading problems?

Use the Virgo Shell Commands as described in this blog.

What's a uses constraint and what can I do if one is violated?

Uses constraints are explained in this blog.

Virgo typically produces helpful diagnostics for uses constraint violations. To solve uses constraint violations, see Rob Harrop's blog and Neil Bartlett's blog.

How can I import a package into someone else's bundle without hacking the manifest?

See this blog.

What support does Virgo have for thread context class loaders?

See this blog.

Are Virgo bundles published to a Maven Repo anywhere.

Yes, they are available over http from http://build.eclipse.org/rt/virgo/maven/bundles/

How can I get a graphical application to work in Virgo?

To get GUI apps to work in Virgo, you have to edit lib/java6-server.profile in order to add some packages to the org.osgi.framework.bootdelegation property.

On Mac, you need to add some Apple packages:

org.osgi.framework.bootdelegation = \
 org.eclipse.virgo.osgi.extensions.*,\
 org.eclipse.virgo.osgi.launcher.*,\
 org.eclipse.virgo.kernel.authentication,\
 com.sun.*,\
 javax.xml.*,\
 org.apache.xerces.jaxp.*,\
 org.w3c.*,\
 org.xml.*,\
 sun.*,\
 apple.*,\
 com.apple.*

On Windows, you just need to add com.sun.* as sun.* is already in the list.

org.osgi.framework.bootdelegation = \
 org.eclipse.virgo.osgi.extensions.*,\
 org.eclipse.virgo.osgi.launcher.*,\
 org.eclipse.virgo.kernel.authentication,\
 com.sun.*,\
 javax.xml.*,\
 org.apache.xerces.jaxp.*,\
 org.w3c.*,\
 org.xml.*,\
 sun.*,\
 com.sun.*

How can I change the version of Spring framework in the user region?

You can upgrade or downgrade the version of Spring framework in the user region provided the new version satisfies the version range required by Virgo. Virgo 3.0.x can use 3.0.x versions of Spring framework. To use Spring framework 3.1.x requires Virgo 3.5.0 or later. To use Spring framework 3.2.x requires Virgo 3.6.0 or later.

To upgrade or downgrade, delete the Spring framework bundles and .libd file in repository/ext and then add the corresponding bundles and .libd file for the replacement version of Spring framework. The Spring framework bundles are listed in the .libd file if you are uncertain about which they are. Then re-start Virgo with the -clean switch and the user region should now run with the replacement version of Spring framework.

Here's an example of upgrading Spring framework on a UNIX system:

cd repository/ext/
rm org.springframework.*-3.0.5.RELEASE.*
cp /.../spring-framework-3.0.6/dist/org.springframework.* .

Note that it is not necessary to change the version of Spring framework used by the Virgo kernel as that version is independent of the version of Spring framework used by the user region.

If you want to use Spring framework 3.2.1 or later on Virgo 3.6.x, you need to upgrade AspectJ to 1.7.1 as follows:

  • Copy com.springsource.org.aspectj.weaver-1.7.1.RELEASE.jar to:
    • repository/ext
    • plugins
  • Update configuration/org.eclipse.virgo.kernel.userregion.properties by changing the AspectJ line to this:
 org.aspectj.*;version="[1.7.1.RELEASE,2.0.0)",\
  • Update configuration/org.eclipse.equinox.simpleconfigurator/bundles.info by changing the AspectJ line to this:
 com.springsource.org.aspectj.weaver,1.7.1.RELEASE,plugins/com.springsource.org.aspectj.weaver-1.7.1.RELEASE.jar,4,false

If you want to use a Spring framework version less than 3.1, you will have to use Virgo 2.1.x, 3.0.x, or 3.5.x. Virgo 3.6.x requires Spring framework 3.1 or later (see bug 398393).

If you want to use a Spring framework version less than 3.0 (for instance 2.5.6.SEC2) you will have to use Virgo 2.1.x or Virgo Jetty Server 3.0. The reason for this is that Virgo Server for Apache Tomcat 3.0.x ships with Tomcat 7 and Servlet 3.0, while Spring framework 2.5.6 import range allows maximum Servlet 2.5 and this makes the two incompatible.

How can I programmatically deploy applications to Virgo?

This can be achieved using the MBeans registered by Virgo. It's best to explore them first using something like JConsole. The deployer MBean can be used to specify an artifact with a URI that should be deployed (installed and started). Prefixes "file:" and "repository:" can be used. In the case of repository a URL of the form "repository://type/name[/version]" will refer to an artifact in a provisioning repository. The square brackets indicate that the trailing "/version" is optional, in which case Virgo uses the highest version available, and are not part of the URL. In the case of a bundle, "type" is "bundle" and "name" is the bundle symbolic name (and if "version" is specified, it is the bundle version).

Note that you can also install bundles using BundleContext.installBundle and they will be installed in the same region as the bundle whose bundle context was used to perform the install. However, bundles installed in this way will not pass through the Virgo deployment pipeline and will not be subject to the transformations normally applied to bundles as they are deployed in Virgo.

My Web Application Bundle stopped working when I moved to Virgo 3.x. What happened?

Virgo Server for Apache Tomcat 3.0 conforms more strictly to the OSGi web applications specification and does not apply default values to some of the manifest headers of a WAB like it used to in Virgo 2.x.

You can easily check whether this is the problem as follows.

As a migration aid, which may be removed in future releases, the previous behaviour may be re-instated by configuring the Web Integration Layer to set WABHeaders=defaulted in $SERVER_HOME/repository/ext/org.eclipse.virgo.web.properties. Please note there is a known issue with certain WAR files which may be worked around using this migration aid.

Should I put Spring XML files in META-INF/spring or WEB-INF?

You should put Spring application context XML configuration files in the WEB-INF directory of a web application bundle and in the META-INF/spring directory of a non-web bundle.

Putting these files in the META-INF/spring directory of a web application bundle is a common mistake and produces unpredictable results since Spring DM will attempt to build an application context independently of, and asynchronously from, the web application.

Why is there both a config and a configuration directory?

The config directory has always contained Virgo configuration files. When Virgo Nano and its support for p2 provisioning was introduced in Virgo 3.5.0, a configuration directory was added (see bug 324991 for details). The directory name configuration in the install's root is used by default in p2.

The Configuration chapter of the Virgo User Guide makes it clear which configuration goes in each directory.

Why is my required bundle with version x.y.z. not resolved?

To specify a version in a Require-Bundle header an (OSGi standard) attribute bundle-version is needed.

Require-Bundle: bar;bundle-version="[x.y.z,x.y.z]"

The attribute is spelled bundle-version= rather than version= as used with Import-Package. A misspelled attribute can show the following error:

   Resolver report:
       A Require-Bundle could not be resolved. Caused by missing constraint in bundle <foo_1.0.0>
            constraint: <Require-Bundle: bar; bundle-version="0.0.0">

If a required bundle cannot be resolved check the spelling of the attribute as well as the location of the required bundle.

What's the difference between Virgo Server for Apache Tomcat and Virgo Jetty Server?

  • Virgo Server for Apache Tomcat (VTS) is based on embedded Tomcat, so its configuration and behaviour is familiar to Tomcat users. Virgo Jetty Server (VJS) is based on Jetty, so its configuration and behaviour is familiar to Jetty users.
  • Please refer to the official Tomcat and Jetty sites for details of these projects.
  • Both VTS and VJS support standard OSGi Web Application Bundles, but only VTS supports WAR files (see bug 336955).
  • VTS supports the hosted repository application and can act as a Virgo repository server, but VJS cannot.
  • VTS embeds Gemini Web which in turn embeds (embedded) Tomcat; VJS embeds Jetty.
  • Virgo Snaps supports VTS but not VJS.
  • VJS has known problems with TagLibs (see bug 349010).

What's the difference between Virgo Server for Apache Tomcat and Virgo Nano Web?

See the feature comparison summary.

What's the difference between Virgo Server for Apache Tomcat and Virgo Tomcat Server?

None. We renamed Virgo Tomcat Server to Virgo Server for Apache Tomcat to conform to Tomcat legal requirements.

What version of the Servlet Specification is supported by Virgo?

  • Virgo Server for Apache Tomcat version 2.x uses embedded Apache Tomcat 6.0.y which supports Servlet Specification 2.5.
  • Virgo Server for Apache Tomcat version 3.x uses embedded Apache Tomcat 7.0.y which supports Servlet Specification 3.0.
  • Virgo Jetty Server version 3.0.x uses Jetty 7.y. which supports Servlet Specification 2.5.
  • Virgo Jetty Server version 3.5.x uses Jetty 8.y which supports Servlet Specification 3.0.