Skip to main content

Notice: this Wiki will be going read only early in 2024 and edits will no longer be possible. Please see: https://gitlab.eclipse.org/eclipsefdn/helpdesk/-/wikis/Wiki-shutdown-plan for the plan.

Jump to: navigation, search

Difference between revisions of "Virgo/Community/Migrating from 3.0.x to 3.5.0"

(Transformer Signature)
(Custom Logback Appenders)
 
(24 intermediate revisions by 3 users not shown)
Line 1: Line 1:
= Modified Directory Layout =
+
= Modified Directory Layout =
  
TBD
+
Virgo's distributions will have a slightly modified directory layout from 3.5.0 onwards. It closely matches an Eclipse-like directory layout. This enables us to seamlessly provide p2 initial provisioning support to all Virgo distributions. The documentation will be thoroughly updated with all changes and the configuration impact on the server.
 +
 
 +
The main differences are:
 +
 
 +
*relocated Virgo configuration directory (from /config to /configuration)
 +
*relocated Equinox configuration folder(from /work/osgi/configuration to /configuration) - this is where the framework stores its caches and other bundle data
 +
*relocated lib/kernel folder(from /lib/kernel to /plugins)
 +
*relocated java6-server.profile (from /lib to /configuration)
 +
 
 +
As as result all configuration files are now located in a single directory - /configuration
 +
This also brings changes to the OSGi configuration of the server previously found in lib/org.eclipse.virgo.kernel.launch.properties. It is now contained in the standard for Equinox config.ini file in the /configuration directory.
 +
 
 +
= New Default Launcher  =
 +
 
 +
Equinox launcher is now the default Virgo Launcher. The consequences of this change are covered in Virgo's user guide in chapter 7 and chapter 7.8 cover the new launcher alone. Most of the startup options remain the same. Different are some of the options that the launcher can accept. The new ones provide means to configure a lot of the framework's internals right from the start.
 +
 
 +
A full list of the options that the Equinox Launcher recognizes is available at [http://help.eclipse.org/indigo/index.jsp?topic=%2Forg.eclipse.platform.doc.isv%2Freference%2Fmisc%2Fruntime-options.html help.eclipse.org]
 +
 
 +
= Spring DM to Gemini Blueprint Upgrade =
 +
 
 +
This release replaces Spring DM 1.2.1 with Gemini Blueprint 1.0.0.RELEASE. Gemini Blueprint supports the OSGi Blueprint standard but is also mostly backward compatible with Spring DM 1.2.1. Please refer to the Gemini Blueprint [http://www.eclipse.org/gemini/blueprint/documentation/migration/ migration notes] for details, especially when migrating applications to use Blueprint instead of Spring DM.
 +
 
 +
One small but significant difference is that Gemini Blueprint does not attach a bean name service property to services constructed from anonymous inner beans ("inside" the <service> element) unlike Spring DM 1.2.1 which attached a service property org.springframework.osgi.bean.name to such services.
 +
 
 +
The service scoping logic in the Virgo kernel was tightened up as a consequence of this change of behaviour. A service published inside a PAR or scoped plan is now only available outside the scope if the service is a Spring DM or blueprint (application) context or if the service property org.eclipse.virgo.service.scope is set to "global". In earlier releases, all services published in a scope without a bean name service property were also available outside the scope.
 +
 
 +
Note that some Blueprint events contain less information than the corresponding Spring DM events so the Virgo kernel still needs a listener which listens to the Spring DM events and issues corresponding Blueprint events but with extra properties which are needed for Virgo's diagnostic support of Blueprint. Blueprint event listeners therefore need to be prepared to see the same event more than once.
 +
 
 +
= Thread Context Class Loading with PARs and Scoped Plans=
 +
 
 +
As described in the Programmer Guide, Virgo creates a synthetic context bundle when a PAR or scoped plan is deployed. The purpose of this bundle is to provide a thread context class loader (TCCL) which can load all types belonging to packages exported by the bundles in the PAR or scoped plan. Unfortunately, in earlier releases, this synthetic context TCCL could be overridden by Spring DM so that a call to a bundle outside the PAR or scoped plan would see the TCCL of the calling bundle rather than of the synthetic context bundle. This problem is fixed in this release by [https://bugs.eclipse.org/bugs/show_bug.cgi?id=360965 bug 360965].
 +
 
 +
However, the fix can impact certain applications which were relying on the bug. For example, the Greenpages sample stopped working because a concrete datasource class could no longer be loaded via the TCCL. The solution was to move the bundle providing the concrete datasource class inside the Greenpages PAR. This seems like a general solution for applications with similar issues. See bug 368781 for [https://bugs.eclipse.org/bugs/show_bug.cgi?id=368781#c18 details] of the Greenpages problem and the fix.
  
 
= Transformer Signature  =
 
= Transformer Signature  =
Line 10: Line 42:
  
 
  public void transform('''GraphNode'''&lt;InstallArtifact&gt; installGraph, InstallEnvironment installEnvironment) throws DeploymentException {
 
  public void transform('''GraphNode'''&lt;InstallArtifact&gt; installGraph, InstallEnvironment installEnvironment) throws DeploymentException {
    installGraph.visit(new ExceptionThrowing'''DirectedAcyclicGraph'''Visitor&lt;InstallArtifact, DeploymentException&gt;() {
+
  installGraph.visit(new ExceptionThrowing'''DirectedAcyclicGraph'''Visitor&lt;InstallArtifact, DeploymentException&gt;() {
 
+
        public boolean visit('''GraphNode'''&lt;InstallArtifact&gt; node) throws DeploymentException {
+
      public boolean visit('''GraphNode'''&lt;InstallArtifact&gt; node) throws DeploymentException {
                InstallArtifact installArtifact = node.getValue();
+
              InstallArtifact installArtifact = node.getValue();
                ...
+
              ...
        }
+
      }
    });
+
  });
 
  }
 
  }
 +
 +
= Custom Logback Appenders =
 +
 +
[https://bugs.eclipse.org/bugs/show_bug.cgi?id=362095 Bug 362095] moved Logback out of the Virgo medic core bundle. This impacts the way that custom appenders are specified.
 +
 +
Fragments containing custom Logback appenders now need to specify:
 +
 +
Fragment-Host: ch.qos.logback.classic
 +
 +
instead of:
 +
 +
Fragment-Host: org.eclipse.virgo.medic.core
 +
 +
Also note that the medic core bundle now sets logback.ignoreTCL to "true" in order to avoid an obscure classloading error in some tests. See bug 362095 for [https://bugs.eclipse.org/bugs/show_bug.cgi?id=362095#c5 details].
 +
 +
= Changed Symbolic Names  =
 +
 +
In 3.5.0 we started consuming some third-party dependencies from Eclipse Orbit instead of EBR. This led to change of some symbolic names previously prefixed with "com.springsource" to a new format without the prefix.
 +
 +
Some examples are:
 +
 +
*com.springsource.javax.ejb =&gt; javax.ejb
 +
*com.springsource.slf4j.api =&gt; org.slf4j.api
 +
*com.springsource.slf4j.bridge =&gt; org.slf4j.jul
 +
*com.sprongsource.ch.qos.logback.core =&gt; ch.qos.logback.core
 +
 +
These upgrades also changed the versions of many org.eclipse bundles like for example Equinox 3.7.x =&gt; 3.8.x.
 +
 +
Logback is also upgraded to 1.0.0 and slf4j.api to 1.6.4.
 +
 +
Possible problem arise if your bundles required some of the old symbolic names in which case you will need to adopt the new ones. There's similar risk with fragments.
 +
 +
= Changed VTS Product Name  =
 +
 +
To conform to [http://tomcat.apache.org/legal.html Apache Tomcat legal requirements], Virgo Tomcat Server is renamed to Virgo Server for Apache Tomcat. This change also applies retrospectively, e.g. on the downloads page.

Latest revision as of 09:02, 14 July 2012

Modified Directory Layout

Virgo's distributions will have a slightly modified directory layout from 3.5.0 onwards. It closely matches an Eclipse-like directory layout. This enables us to seamlessly provide p2 initial provisioning support to all Virgo distributions. The documentation will be thoroughly updated with all changes and the configuration impact on the server.

The main differences are:

  • relocated Virgo configuration directory (from /config to /configuration)
  • relocated Equinox configuration folder(from /work/osgi/configuration to /configuration) - this is where the framework stores its caches and other bundle data
  • relocated lib/kernel folder(from /lib/kernel to /plugins)
  • relocated java6-server.profile (from /lib to /configuration)

As as result all configuration files are now located in a single directory - /configuration This also brings changes to the OSGi configuration of the server previously found in lib/org.eclipse.virgo.kernel.launch.properties. It is now contained in the standard for Equinox config.ini file in the /configuration directory.

New Default Launcher

Equinox launcher is now the default Virgo Launcher. The consequences of this change are covered in Virgo's user guide in chapter 7 and chapter 7.8 cover the new launcher alone. Most of the startup options remain the same. Different are some of the options that the launcher can accept. The new ones provide means to configure a lot of the framework's internals right from the start.

A full list of the options that the Equinox Launcher recognizes is available at help.eclipse.org

Spring DM to Gemini Blueprint Upgrade

This release replaces Spring DM 1.2.1 with Gemini Blueprint 1.0.0.RELEASE. Gemini Blueprint supports the OSGi Blueprint standard but is also mostly backward compatible with Spring DM 1.2.1. Please refer to the Gemini Blueprint migration notes for details, especially when migrating applications to use Blueprint instead of Spring DM.

One small but significant difference is that Gemini Blueprint does not attach a bean name service property to services constructed from anonymous inner beans ("inside" the <service> element) unlike Spring DM 1.2.1 which attached a service property org.springframework.osgi.bean.name to such services.

The service scoping logic in the Virgo kernel was tightened up as a consequence of this change of behaviour. A service published inside a PAR or scoped plan is now only available outside the scope if the service is a Spring DM or blueprint (application) context or if the service property org.eclipse.virgo.service.scope is set to "global". In earlier releases, all services published in a scope without a bean name service property were also available outside the scope.

Note that some Blueprint events contain less information than the corresponding Spring DM events so the Virgo kernel still needs a listener which listens to the Spring DM events and issues corresponding Blueprint events but with extra properties which are needed for Virgo's diagnostic support of Blueprint. Blueprint event listeners therefore need to be prepared to see the same event more than once.

Thread Context Class Loading with PARs and Scoped Plans

As described in the Programmer Guide, Virgo creates a synthetic context bundle when a PAR or scoped plan is deployed. The purpose of this bundle is to provide a thread context class loader (TCCL) which can load all types belonging to packages exported by the bundles in the PAR or scoped plan. Unfortunately, in earlier releases, this synthetic context TCCL could be overridden by Spring DM so that a call to a bundle outside the PAR or scoped plan would see the TCCL of the calling bundle rather than of the synthetic context bundle. This problem is fixed in this release by bug 360965.

However, the fix can impact certain applications which were relying on the bug. For example, the Greenpages sample stopped working because a concrete datasource class could no longer be loaded via the TCCL. The solution was to move the bundle providing the concrete datasource class inside the Greenpages PAR. This seems like a general solution for applications with similar issues. See bug 368781 for details of the Greenpages problem and the fix.

Transformer Signature

Transformer services in Virgo 3.5.0 operate in terms of a directed acyclic graph of install artefacts instead of the tree which was used by Virgo 3.0.x.

If you provide a Transformer service, you'll need to rework it to implement the modified signature. For example, the WebTransformer.transform method was changed as follows:

public void transform(GraphNode<InstallArtifact> installGraph, InstallEnvironment installEnvironment) throws DeploymentException {
 installGraph.visit(new ExceptionThrowingDirectedAcyclicGraphVisitor<InstallArtifact, DeploymentException>() {

     public boolean visit(GraphNode<InstallArtifact> node) throws DeploymentException {
             InstallArtifact installArtifact = node.getValue();
             ...
     }
 });
}

Custom Logback Appenders

Bug 362095 moved Logback out of the Virgo medic core bundle. This impacts the way that custom appenders are specified.

Fragments containing custom Logback appenders now need to specify:

Fragment-Host: ch.qos.logback.classic

instead of:

Fragment-Host: org.eclipse.virgo.medic.core

Also note that the medic core bundle now sets logback.ignoreTCL to "true" in order to avoid an obscure classloading error in some tests. See bug 362095 for details.

Changed Symbolic Names

In 3.5.0 we started consuming some third-party dependencies from Eclipse Orbit instead of EBR. This led to change of some symbolic names previously prefixed with "com.springsource" to a new format without the prefix.

Some examples are:

  • com.springsource.javax.ejb => javax.ejb
  • com.springsource.slf4j.api => org.slf4j.api
  • com.springsource.slf4j.bridge => org.slf4j.jul
  • com.sprongsource.ch.qos.logback.core => ch.qos.logback.core

These upgrades also changed the versions of many org.eclipse bundles like for example Equinox 3.7.x => 3.8.x.

Logback is also upgraded to 1.0.0 and slf4j.api to 1.6.4.

Possible problem arise if your bundles required some of the old symbolic names in which case you will need to adopt the new ones. There's similar risk with fragments.

Changed VTS Product Name

To conform to Apache Tomcat legal requirements, Virgo Tomcat Server is renamed to Virgo Server for Apache Tomcat. This change also applies retrospectively, e.g. on the downloads page.

Back to the top