programmer-guide/src/known-issues.xml

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
		"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<chapter id="known-issues">
	<title>Known Issues</title>
	<section id="known-issues-jpa">
		<title>JPA Entity Scanning</title>
		<para>
			Classpath scanning for JPA entities annotated with <literal>@Entity</literal> does
			not work. Describing entities with <literal>@Entity</literal> will work, but the
			entities need to be listed explicitly.
		</para>
	</section>
	<section id="known.issues.proxy">
		<title><classname>ClassNotFoundError</classname> When Creating a Proxy</title>
		<para>
			When creating proxies at runtime, there are circumstances where <classname>ClassNotFoundErrors</classname>
			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
			<ulink url="http://www.osgi.org/blog/2008/08/classy-solutions-to-tricky-proxies.html">this blog entry</ulink>
			for more details.
		</para>
	</section>
	<section id="known.issues.cglib">
		<title>Creating proxies with CGLIB for package-protected types</title>
		<para>
			In traditional Java EE applications user types are loaded by the same <classname>ClassLoader</classname> 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 <classname>ClassLoaders</classname>. This prevents CGLIB from proxying any package-protected types.
		</para>
		<para>
			The workaround for this issue is to make all types that require proxying public.
		</para>
	</section>
	<section id="known-issues-tomcat-restrictions">
		<title>Tomcat Restrictions</title>
		<para>
			The following Tomcat features are not supported.
			<itemizedlist>
				<listitem>
					<literal>&lt;Context&gt;</literal> elements.
				</listitem>	
			</itemizedlist>
		</para>
	</section>
	<section id="known-issues-web-bundle-default-headers">
		<title>Default Web Application Bundle Headers</title>
		<para>
			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 below) and so Virgo modifies the behaviour of Gemini Web so that it applies default
			values consistently with dm Server 2.0.x.
		</para>
		<para>
			This restriction is intended to ease migration to Virgo 2.1.0 and may be removed in a later release.
		</para>
		<para>
			The following defaults are applied to a Web Application Bundle:
			<itemizedlist>
				<listitem>
					<literal>Bundle-ManifestVersion</literal> is set to <literal>2</literal>
				</listitem>
				<listitem>
					<literal>Bundle-SymbolicName</literal> is generated from the path from which the bundle was installed
				</listitem>
				<listitem>
					<literal>Bundle-ClassPath</literal> is set to <literal>WEB-INF/classes</literal> followed by the JARs in
					<literal>WEB-INF/lib</literal> in an unspecified order, followed by any transitive dependencies declared
					by the JARs in <literal>WEB-INF/lib</literal>
				</listitem>
				<listitem>
					<literal>Import-Package</literal> is extended to import a fixed set of <classname>javax.servlet.*</classname>
					packages, <classname>javax.el</classname>, and packages which are exported by the system bundle but not
					provided by the bundle (see <link linkend="developing-applications-automatic-imports-web">Automatic Imports
					for the Web Personality</link> for details)
				</listitem>
			</itemizedlist>
		</para>
	</section>
	<section id="hibernate-resolution-issue">
		<title>Hibernate Resolution Issue</title>
		<para>
			Applications using Hibernate 3.4.0.GA need to upgrade the Hibernate EJB 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
			<literal>org.hibernate.ejb.transaction</literal>.
			See <ulink url="https://bugs.eclipse.org/bugs/show_bug.cgi?id=335174">bug 335174</ulink> for details.
		</para>
		<para>
			The Hibernate EJB fragment bundle <literal>com.springsource.org.hibernate.ejb</literal> v3.4.0.GA in the
			<ulink url="http://ebr.springsource.com/repository/app/">SpringSource Enterprise Bundle Repository</ulink>
			depends on the package <literal>org.slf4j</literal> 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
			<literal>com.springsource.org.hibernate</literal> and the host then does not export the packages the application
			may need, such as <literal>org.hibernate.ejb.transaction</literal>.
		</para>
		<para>
			An updated Hibernate EJB fragment with version 3.4.0.GA-A which fixes this problem is available from the
			<ulink url="http://ebr.springsource.com/repository/app/">SpringSource Enterprise Bundle Repository</ulink>.
		</para>
	</section>	
</chapter>