:virgo-name: Virgo
:version: 3.7.0.RELEASE

:umbrella-virgo-name: Eclipse Virgo
:tomcat-product-name: Virgo for Apache Tomcat
:tomcat-product-name-short: VTS
:jetty-product-name: Virgo Jetty Server
:jetty-product-name-short: VJS
:kernel-product-name: Virgo Kernel
:kernel-product-name-short: VK
:nano-product-name: Virgo Nano
:nano-product-name-short: VN
:user-guide: link:../../virgo-user-guide/html/index.html[User Guide]
:tooling-guide: link:../../virgo-tooling-guide/html/index.html[Tooling Guide]

:gemini-blueprint-guide: https://www.eclipse.org/gemini/blueprint/documentation/reference/2.0.0.RELEASE/html/index.html[Eclipse Gemini Blueprint Reference Guide]

:spring-framework-version: 4.2.9.RELEASE

:homepage: https://www.eclipse.org/virgo
:ebr: http://www.eclipse.org/ebr[EBR]

:imagesdir: assets/images

anchor:known-issues[]

== Known Issues

anchor:known-issues-jpa[]

=== JPA Entity Scanning

Classpath scanning for JPA entities annotated with `@Entity` does
not work. Describing entities with `@Entity` will work, but the
entities need to be listed explicitly.

anchor:known.issues.proxy[]

=== `ClassNotFoundError` When Creating a Proxy

When creating proxies at runtime, there are circumstances where `ClassNotFoundErrors`
can be generated. These errors happen because the proxy creating bundle does not have visibility into every
type on the interface of the proxy. You can either put in import statements for all the relevant types or
add use a service (with visibility of all pertinent types) to create the proxy. Please see
http://www.osgi.org/blog/2008/08/classy-solutions-to-tricky-proxies.html[this blog entry]
for more details.

anchor:known.issues.cglib[]

=== Creating proxies with CGLIB for Package Protected Types

In traditional Java EE applications user types are loaded by the same `ClassLoader` as
CGLIB. This allows CGLIB to proxy package-protected types. In OSGi environments, user types and CGLIB will
most likely be packaged in separate bundles. This results in the user types and CGLIB being loaded by
different `ClassLoaders`. This prevents CGLIB from proxying any package-protected types.

The workaround for this issue is to make all types that require proxying public.

anchor:known-issues-jetty-restrictions[]

=== {jetty-product-name} Restrictions

The following Jetty features are not supported.

* Tag Libraries other than the standard Apache Tag Library.

anchor:known-issues-web-bundle-default-headers[]

=== Default Web Application Bundle Headers

The Gemini Web container conforms to the OSGi Web Applications specification and does not apply default values
to the headers of a Web Application Bundle. However, SpringSource dm Server 2.0.x applies default values
to certain headers (see xref:developing-applications-automatic-imports-web[Web Application Manifest
Processing] for details) and so Virgo Web Server 2.1.x modified the behaviour of Gemini Web so that it applied default
values consistently with dm Server 2.0.x.

This behaviour is changed as of {tomcat-product-name} 3.0. {tomcat-product-name-short} now conforms strictly to the
OSGi Web Applications specification.

As a migration aid, *which may not be supported in a future release*, users may configure the {tomcat-product-name-short} Web Integration
Layer to apply default values to the headers of a Web Application Bundle.
See "Configuring the Web Integration Layer" in the {user-guide} for details.

anchor:hibernate-resolution-issue[]

=== Hibernate Resolution Issue

Applications using Hibernate 3.4.0.GA need to upgrade the JBoss Hibernate Entity manager fragment bundle to version 3.4.0.GA-A.
The symptoms are that the application will fail to resolve due to missing imports of packages such as `org.hibernate.ejb.transaction`
and JBoss Hibernate Annotations `com.springsource.org.hibernate.annotations`.
See https://bugs.eclipse.org/bugs/show_bug.cgi?id=335174[bug 335174] for details.

The JBoss Hibernate Entity manager fragment bundle `com.springsource.org.hibernate.ejb` v3.4.0.GA in the
http://ebr.springsource.com/repository/app/[SpringSource Enterprise Bundle Repository]
depends on the package `org.slf4j` with a version range that excludes the version of the
package provided with Virgo. The net effect is that Hibernate EJB fragment bundle fails to attach to its host
`com.springsource.org.hibernate` and the host then does not export the packages the application
may need, such as `org.hibernate.ejb.transaction`.

An updated JBoss Hibernate Entity manager fragment and JBoss Hibernate Annotations with versions 3.4.0.GA-A which fixes this
problem is available from the http://ebr.springsource.com/repository/app/[SpringSource Enterprise Bundle Repository].

anchor:scoping-and-substitutable-exports[]

=== Scoping and Substitutable Exports

The restriction described in xref:developing-applications-plans-scoping[Plans and Scoping] that
no package may be exported by more than one	bundle in a given scope can cause problems for bundles with
*substitutable exports*. A substitutable export is a package which is exported and imported
by the same bundle. The OSGi framework will discard either the import or the export of the package when the
bundle is resolved.

However, if more than one bundle in a scope has a substitutable export of the same package, then Virgo will fail
to deploy the scoped application because the above restriction appears to be broken. Virgo could only spot that
the restriction was not actually being broken by second guessing the resolution behaviour of the OSGi framework,
something that Virgo generally avoids because of the fragility of that approach.

It may be possible to work around this issue by omitting one of the bundles containing the substitutable export
from the scoped application.

It may also be possible to work around this issue by moving the bundles containing the substitutable exports outside the scope,
although this will not give correct behaviour if the bundles' exported packages need to be available for thread
context class loading.

See https://bugs.eclipse.org/bugs/show_bug.cgi?id=330643[bug 330643] for an example of this issue.

anchor:eclipselink-resolution-issue[]

=== EclipseLink Resolution Issue

Applications using EclipseLink may fail to resolve if the `osgi.enterprise` bundle is allowed to
wire its `javax.persistence` package import to other than the EclipseLink `javax.persistence` bundle.

To avoid this, install EclipseLink's `javax.persistence` bundle early. To install this bundle before
any applications are deployed, list the bundle in the `initialArtifacts` property described in the
{user-guide}.

See https://bugs.eclipse.org/bugs/show_bug.cgi?id=337826[bug 337826] for details.