programmer-guide/src/docs/asciidoc/known-issues.adoc - virgo/org.eclipse.virgo.documentation - Git at Google

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

 :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.
	:virgo-name: Virgo
	:version: 3.7.0.RC01

	: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.